docs: Starlight documentation site

docs/.gitignore

@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

docs/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

docs/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

docs/README.md

@@ -0,0 +1,49 @@
+# Starlight Starter Kit: Basics
+
+[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+
+```
+pnpm create astro@latest -- --template starlight
+```
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+## 🚀 Project Structure
+
+Inside of your Astro + Starlight project, you'll see the following folders and files:
+
+```
+.
+├── public/
+├── src/
+│   ├── assets/
+│   ├── content/
+│   │   └── docs/
+│   └── content.config.ts
+├── astro.config.mjs
+├── package.json
+└── tsconfig.json
+```
+
+Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
+
+Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+
+Static assets, like favicons, can be placed in the `public/` directory.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action                                           |
+| :------------------------ | :----------------------------------------------- |
+| `pnpm install`             | Installs dependencies                            |
+| `pnpm dev`             | Starts local dev server at `localhost:4321`      |
+| `pnpm build`           | Build your production site to `./dist/`          |
+| `pnpm preview`         | Preview your build locally, before deploying     |
+| `pnpm astro ...`       | Run CLI commands like `astro add`, `astro check` |
+| `pnpm astro -- --help` | Get help using the Astro CLI                     |
+
+## 👀 Want to learn more?
+
+Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).

docs/astro.config.mjs

@@ -0,0 +1,124 @@
+// @ts-check
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
+
+// https://astro.build/config
+export default defineConfig({
+	site: "https://getcirrus.dev",
+	integrations: [
+		starlight({
+			title: "Cirrus",
+			description:
+				"The lightest PDS in the Atmosphere. A single-user AT Protocol Personal Data Server that runs on a Cloudflare Worker.",
+			logo: {
+				src: "./src/assets/cloud.svg",
+				alt: "",
+			},
+			social: [
+				{
+					icon: "github",
+					label: "GitHub",
+					href: "https://github.com/ascorbic/cirrus",
+				},
+			],
+			editLink: {
+				baseUrl: "https://github.com/ascorbic/cirrus/edit/main/docs/",
+			},
+			sidebar: [
+				{
+					label: "Start here",
+					items: [
+						{ label: "Welcome", slug: "index" },
+						{ label: "Why run a PDS", slug: "start/why" },
+						{ label: "Prerequisites", slug: "start/prerequisites" },
+						{ label: "Quick start", slug: "start/quick-start" },
+						{ label: "First login", slug: "start/first-login" },
+					],
+				},
+				{
+					label: "Concepts",
+					items: [
+						{
+							label: "The AT Protocol in 5 minutes",
+							slug: "concepts/atproto",
+						},
+						{ label: "How Cirrus is built", slug: "concepts/architecture" },
+						{
+							label: "Identity and your signing key",
+							slug: "concepts/identity",
+						},
+						{ label: "Authentication methods", slug: "concepts/auth" },
+						{ label: "The firehose", slug: "concepts/firehose" },
+						{ label: "Data placement", slug: "concepts/data-placement" },
+						{ label: "Costs and limits", slug: "concepts/costs-and-limits" },
+					],
+				},
+				{
+					label: "Guides",
+					items: [
+						{
+							label: "Migrate from Bluesky",
+							slug: "guides/migrate-from-bluesky",
+						},
+						{
+							label: "Migrate to another PDS",
+							slug: "guides/migrate-to-another-pds",
+						},
+						{ label: "Choose a handle", slug: "guides/choose-a-handle" },
+						{
+							label: "Back up your signing key",
+							slug: "guides/back-up-signing-key",
+						},
+						{ label: "Sign in to Bluesky", slug: "guides/sign-in-to-bluesky" },
+						{
+							label: "Set up passkey login",
+							slug: "guides/passkey-login",
+						},
+						{
+							label: "Create an app password",
+							slug: "guides/app-password",
+						},
+						{ label: "Update a deployed PDS", slug: "guides/update" },
+						{ label: "Troubleshoot common errors", slug: "guides/troubleshoot" },
+					],
+				},
+				{
+					label: "Operate",
+					items: [
+						{ label: "Deploy checklist", slug: "operate/deploy-checklist" },
+						{ label: "Monitor your PDS", slug: "operate/monitor" },
+						{
+							label: "Manage secrets and rotate keys",
+							slug: "operate/secrets",
+						},
+					],
+				},
+				{
+					label: "Reference",
+					items: [
+						{ label: "pds CLI", slug: "reference/pds-cli" },
+						{ label: "create-pds CLI", slug: "reference/create-pds-cli" },
+						{
+							label: "Environment variables",
+							slug: "reference/environment-variables",
+						},
+						{ label: "wrangler.jsonc", slug: "reference/wrangler-config" },
+						{
+							label: "Implemented endpoints",
+							slug: "reference/endpoints",
+						},
+						{ label: "OAuth 2.1 surface", slug: "reference/oauth" },
+						{ label: "Glossary", slug: "reference/glossary" },
+					],
+				},
+				{
+					label: "Project",
+					items: [
+						{ label: "Status and roadmap", slug: "project/status" },
+						{ label: "Contributing", slug: "project/contributing" },
+					],
+				},
+			],
+		}),
+	],
+});

docs/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "docs",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.39.2",
+    "astro": "^6.3.1",
+    "hls.js": "^1.6.16",
+    "plyr": "^3.8.4"
+  }
+}

docs/src/components/VodPlayer.astro

@@ -0,0 +1,138 @@
+---
+interface Props {
+	vodAtUri: string;
+	title: string;
+}
+
+const VOD_PLAYBACK_BASE =
+	"https://vod-beta.stream.place/xrpc/place.stream.playback.getVideoPlaylist";
+
+const { vodAtUri, title } = Astro.props;
+const playlistUrl = `${VOD_PLAYBACK_BASE}?uri=${encodeURIComponent(vodAtUri)}`;
+---
+
+<div class="vod-player" data-playlist-url={playlistUrl} data-title={title}>
+	<div class="vod-player-wrap">
+		<video class="vod-video" aria-label={title}></video>
+	</div>
+	<div class="vod-error" hidden>
+		<p>Failed to load video</p>
+	</div>
+</div>
+
+<script>
+	import Hls from "hls.js";
+	import Plyr from "plyr";
+	import "plyr/dist/plyr.css";
+
+	document.querySelectorAll<HTMLElement>(".vod-player").forEach((container) => {
+		const playlistUrl = container.dataset.playlistUrl!;
+		const videoEl = container.querySelector<HTMLVideoElement>(".vod-video")!;
+		const wrap = container.querySelector<HTMLElement>(".vod-player-wrap")!;
+		const errorEl = container.querySelector<HTMLElement>(".vod-error")!;
+
+		let hls: Hls | null = null;
+
+		function showError() {
+			wrap.hidden = true;
+			errorEl.hidden = false;
+		}
+
+		try {
+			if (Hls.isSupported()) {
+				hls = new Hls({ autoStartLoad: false });
+				hls.loadSource(playlistUrl);
+				hls.attachMedia(videoEl);
+				hls.on(Hls.Events.ERROR, (_event, data) => {
+					if (data.fatal) {
+						if (data.type === Hls.ErrorTypes.NETWORK_ERROR) {
+							hls?.startLoad();
+						} else if (data.type === Hls.ErrorTypes.MEDIA_ERROR) {
+							hls?.recoverMediaError();
+						} else {
+							showError();
+						}
+					}
+				});
+			} else if (videoEl.canPlayType("application/vnd.apple.mpegurl")) {
+				videoEl.src = playlistUrl;
+			} else {
+				showError();
+				return;
+			}
+
+			const plyr = new Plyr(videoEl, {
+				controls: [
+					"play-large",
+					"play",
+					"progress",
+					"current-time",
+					"mute",
+					"volume",
+					"settings",
+					"fullscreen",
+				],
+				settings: ["speed"],
+				speed: {
+					selected: 1,
+					options: [0.5, 0.75, 1, 1.25, 1.5, 1.75, 2],
+				},
+				ratio: "16:9",
+			});
+
+			plyr.on("play", () => {
+				hls?.startLoad();
+			});
+		} catch {
+			showError();
+		}
+	});
+</script>
+
+<style>
+	.vod-player {
+		--plyr-color-main: var(--sl-color-accent);
+		--plyr-video-background: #000;
+		--plyr-video-control-color: #fff;
+		--plyr-video-control-background-hover: rgba(255, 255, 255, 0.15);
+		--plyr-video-controls-background: linear-gradient(
+			transparent,
+			rgba(0, 0, 0, 0.75)
+		);
+		margin: 1.5rem 0;
+	}
+
+	.vod-player-wrap {
+		aspect-ratio: 16 / 9;
+		width: 100%;
+		max-width: 100%;
+		overflow: hidden;
+		border-radius: 0.5rem;
+		border: 1px solid var(--sl-color-gray-5);
+	}
+
+	.vod-player-wrap :global(video) {
+		width: 100%;
+		height: 100%;
+	}
+
+	.vod-error {
+		aspect-ratio: 16 / 9;
+		width: 100%;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		border-radius: 0.5rem;
+		border: 1px solid var(--sl-color-gray-5);
+		background: var(--sl-color-gray-6);
+	}
+
+	.vod-error[hidden] {
+		display: none;
+	}
+
+	.vod-error p {
+		color: var(--sl-color-gray-3);
+		font-size: 0.875rem;
+	}
+</style>

docs/src/content.config.ts

@@ -0,0 +1,7 @@
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+	docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};