audio streaming app
plyr.fm
docs: publish docs with Starlight at docs.plyr.fm (#1028)
* docs: publish docs with Starlight at docs.plyr.fm
adds a Starlight (Astro) docs site that symlinks to the existing docs/
directory, keeping it as the single source of truth. includes:
- frontmatter injection across all ~65 markdown files
- docs-site/ scaffold with astro config, sidebar, and justfile
- contributing.md synthesized from setup, README, STATUS, and CLAUDE.md
- root justfile mod for `just docs run/build`
- loq limit bumps for 4 docs files (+4 lines from frontmatter)
Cloudflare Pages project setup is manual (see PR description).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* add GHA workflow for docs deployment via wrangler pages deploy
- path-filtered: triggers on docs/** and docs-site/** changes
- uses cloudflare/wrangler-action for deployment
- documents docs site in deployment/environments.md
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: add landing page and match plyr.fm visual style
- add docs/index.md with splash template hero page
- custom CSS: plyr.fm colors (#0a0a0a bg, #6a9fff accent),
monospace font stack, light mode overrides
- homepage no longer 404s
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: remove duplicate h1 headings and normalize title casing
Starlight renders the frontmatter title as an h1, so the body # heading
was doubling every page title. stripped all body h1s and normalized
casing to lowercase aesthetic (respecting proper nouns).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: drop "decentralized" from docs tagline
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
authored by
Claude Opus 4.6
and committed by
GitHub
0acd8411
bcc79c1e
+34
.github/workflows/deploy-docs.yml
+34
.github/workflows/deploy-docs.yml
···
1
+
name: deploy docs
2
+
3
+
on:
4
+
push:
5
+
branches:
6
+
- main
7
+
paths:
8
+
- "docs/**"
9
+
- "docs-site/**"
10
+
- ".github/workflows/deploy-docs.yml"
11
+
workflow_dispatch:
12
+
13
+
jobs:
14
+
deploy:
15
+
name: deploy docs
16
+
runs-on: ubuntu-latest
17
+
concurrency: deploy-docs
18
+
permissions:
19
+
contents: read
20
+
deployments: write
21
+
steps:
22
+
- uses: actions/checkout@v4
23
+
24
+
- uses: oven-sh/setup-bun@v2
25
+
26
+
- name: build
27
+
run: cd docs-site && bun install && bun run build
28
+
29
+
- name: deploy to cloudflare pages
30
+
uses: cloudflare/wrangler-action@v3
31
+
with:
32
+
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
33
+
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
34
+
command: pages deploy docs-site/dist --project-name plyr-fm-docs --branch main
+3
.gitignore
+3
.gitignore
+66
docs-site/astro.config.mjs
+66
docs-site/astro.config.mjs
···
1
+
import { defineConfig } from "astro/config";
2
+
import starlight from "@astrojs/starlight";
3
+
4
+
export default defineConfig({
5
+
site: "https://docs.plyr.fm",
6
+
integrations: [
7
+
starlight({
8
+
title: "plyr.fm docs",
9
+
favicon: "/favicon.svg",
10
+
social: [
11
+
{
12
+
icon: "github",
13
+
label: "GitHub",
14
+
href: "https://github.com/zzstoatzz/plyr.fm",
15
+
},
16
+
],
17
+
sidebar: [
18
+
{
19
+
label: "getting started",
20
+
items: [
21
+
{ slug: "local-development/setup" },
22
+
{ slug: "contributing" },
23
+
],
24
+
},
25
+
{
26
+
label: "guides",
27
+
items: [
28
+
{ slug: "authentication" },
29
+
{ slug: "security" },
30
+
{ slug: "rate-limiting" },
31
+
{ slug: "offboarding" },
32
+
{ slug: "content-gating-roadmap" },
33
+
],
34
+
},
35
+
{
36
+
label: "architecture",
37
+
autogenerate: { directory: "architecture" },
38
+
},
39
+
{ label: "backend", autogenerate: { directory: "backend" } },
40
+
{ label: "frontend", autogenerate: { directory: "frontend" } },
41
+
{
42
+
label: "deployment",
43
+
autogenerate: { directory: "deployment" },
44
+
},
45
+
{
46
+
label: "moderation",
47
+
autogenerate: { directory: "moderation" },
48
+
},
49
+
{ label: "tools", autogenerate: { directory: "tools" } },
50
+
{ label: "testing", autogenerate: { directory: "testing" } },
51
+
{ label: "lexicons", autogenerate: { directory: "lexicons" } },
52
+
{ label: "runbooks", autogenerate: { directory: "runbooks" } },
53
+
{
54
+
label: "legal",
55
+
items: [{ slug: "legal/privacy" }, { slug: "legal/terms" }],
56
+
},
57
+
],
58
+
customCss: ["./src/styles/custom.css"],
59
+
}),
60
+
],
61
+
vite: {
62
+
resolve: {
63
+
preserveSymlinks: true,
64
+
},
65
+
},
66
+
});
docs-site/bun.lockb
docs-site/bun.lockb
This is a binary file and will not be displayed.
+17
docs-site/justfile
+17
docs-site/justfile
+17
docs-site/package.json
+17
docs-site/package.json
···
1
+
{
2
+
"name": "plyr-fm-docs",
3
+
"type": "module",
4
+
"version": "0.0.1",
5
+
"scripts": {
6
+
"dev": "astro dev",
7
+
"start": "astro dev",
8
+
"build": "astro build",
9
+
"preview": "astro preview",
10
+
"astro": "astro"
11
+
},
12
+
"dependencies": {
13
+
"@astrojs/starlight": "^0.34",
14
+
"astro": "^5",
15
+
"sharp": "^0.33"
16
+
}
17
+
}
+3
docs-site/public/favicon.svg
+3
docs-site/public/favicon.svg
+7
docs-site/src/content.config.ts
+7
docs-site/src/content.config.ts
+1
docs-site/src/content/docs
+1
docs-site/src/content/docs
···
1
+
../../../docs
+43
docs-site/src/styles/custom.css
+43
docs-site/src/styles/custom.css
···
1
+
/* match plyr.fm dark-first aesthetic */
2
+
3
+
/* dark mode (default) */
4
+
:root {
5
+
/* accent: plyr.fm periwinkle blue #6a9fff */
6
+
--sl-color-accent-low: hsl(218, 50%, 15%);
7
+
--sl-color-accent: #6a9fff;
8
+
--sl-color-accent-high: #c0d8ff;
9
+
--sl-color-text-accent: #6a9fff;
10
+
11
+
/* grays matched to plyr.fm bg/border/text tokens */
12
+
--sl-color-white: #e8e8e8;
13
+
--sl-color-gray-1: #b0b0b0;
14
+
--sl-color-gray-2: #808080;
15
+
--sl-color-gray-3: #666666;
16
+
--sl-color-gray-4: #444444;
17
+
--sl-color-gray-5: #1a1a1a;
18
+
--sl-color-gray-6: #141414;
19
+
--sl-color-black: #0a0a0a;
20
+
21
+
/* monospace font stack from plyr.fm */
22
+
--sl-font: 'SF Mono', 'Monaco', 'Inconsolata', 'Fira Code', 'Consolas',
23
+
monospace;
24
+
--sl-font-system-mono: 'SF Mono', 'Monaco', 'Inconsolata', 'Fira Code',
25
+
'Consolas', monospace;
26
+
}
27
+
28
+
/* light mode */
29
+
:root[data-theme='light'] {
30
+
--sl-color-accent-low: hsl(218, 60%, 92%);
31
+
--sl-color-accent: #4a7ddd;
32
+
--sl-color-accent-high: #1a3a6a;
33
+
--sl-color-text-accent: #4a7ddd;
34
+
35
+
--sl-color-white: #fafafa;
36
+
--sl-color-gray-1: #171717;
37
+
--sl-color-gray-2: #525252;
38
+
--sl-color-gray-3: #737373;
39
+
--sl-color-gray-4: #a3a3a3;
40
+
--sl-color-gray-5: #e5e5e5;
41
+
--sl-color-gray-6: #f5f5f5;
42
+
--sl-color-black: #ffffff;
43
+
}
+3
docs-site/wrangler.toml
+3
docs-site/wrangler.toml
+3
-1
docs/CLAUDE.md
+3
-1
docs/CLAUDE.md
+3
-1
docs/README.md
+3
-1
docs/README.md
+3
-1
docs/architecture/jams-queue-integration.md
+3
-1
docs/architecture/jams-queue-integration.md
+3
-1
docs/architecture/jams-transport-decision.md
+3
-1
docs/architecture/jams-transport-decision.md
+3
-1
docs/architecture/jams.md
+3
-1
docs/architecture/jams.md
+3
-1
docs/authentication.md
+3
-1
docs/authentication.md
+3
-1
docs/backend/atproto-identity.md
+3
-1
docs/backend/atproto-identity.md
+3
-1
docs/backend/background-tasks.md
+3
-1
docs/backend/background-tasks.md
+3
-1
docs/backend/configuration.md
+3
-1
docs/backend/configuration.md
+3
-1
docs/backend/database/connection-pooling.md
+3
-1
docs/backend/database/connection-pooling.md
+3
-1
docs/backend/database/neon.md
+3
-1
docs/backend/database/neon.md
+3
-1
docs/backend/feature-flags.md
+3
-1
docs/backend/feature-flags.md
+3
-1
docs/backend/genre-classification.md
+3
-1
docs/backend/genre-classification.md
+3
-1
docs/backend/liked-tracks.md
+3
-1
docs/backend/liked-tracks.md
+3
-1
docs/backend/mood-search.md
+3
-1
docs/backend/mood-search.md
+3
-1
docs/backend/playlist-recommendations.md
+3
-1
docs/backend/playlist-recommendations.md
+3
-1
docs/backend/streaming-uploads.md
+3
-1
docs/backend/streaming-uploads.md
+3
-1
docs/backend/transcoder.md
+3
-1
docs/backend/transcoder.md
+3
-1
docs/content-gating-roadmap.md
+3
-1
docs/content-gating-roadmap.md
+155
docs/contributing.md
+155
docs/contributing.md
···
1
+
---
2
+
title: "contributing"
3
+
---
4
+
5
+
guide for contributing to plyr.fm.
6
+
7
+
## getting started
8
+
9
+
### prerequisites
10
+
11
+
- **python**: 3.11+ (managed via [`uv`](https://docs.astral.sh/uv/))
12
+
- **bun**: for frontend development
13
+
- **postgres**: local database (optional — can use neon dev instance)
14
+
15
+
### setup
16
+
17
+
```bash
18
+
gh repo clone zzstoatzz/plyr.fm
19
+
cd plyr.fm
20
+
21
+
# install dependencies
22
+
uv sync
23
+
cd frontend && bun install && cd ..
24
+
25
+
# configure environment
26
+
cp .env.example .env
27
+
# edit .env with your credentials (see local-development/setup for details)
28
+
29
+
# start backend (terminal 1)
30
+
just backend run
31
+
32
+
# start frontend (terminal 2)
33
+
just frontend run
34
+
```
35
+
36
+
visit http://localhost:5173 to see the app. see [local development setup](./local-development/setup.md) for complete environment configuration, database setup, and troubleshooting.
37
+
38
+
## development workflow
39
+
40
+
1. **check [`STATUS.md`](https://github.com/zzstoatzz/plyr.fm/blob/main/STATUS.md)** for active tasks and known issues
41
+
2. **create a GitHub issue** describing the change (we use GitHub Issues, not Linear)
42
+
3. **branch from `main`**, make your changes
43
+
4. **open a PR** for review — never push directly to main
44
+
5. merging to `main` auto-deploys to **staging** (`stg.plyr.fm`). production requires `just release`
45
+
46
+
### running tests
47
+
48
+
```bash
49
+
# from repo root (not from backend/)
50
+
just backend test
51
+
52
+
# specific test file
53
+
uv run pytest tests/api/test_tracks.py -v
54
+
55
+
# with coverage
56
+
uv run pytest --cov=backend
57
+
```
58
+
59
+
always add regression tests when fixing bugs.
60
+
61
+
### linting
62
+
63
+
```bash
64
+
just backend lint # python (ruff)
65
+
just frontend check # svelte (svelte-check)
66
+
```
67
+
68
+
### database migrations
69
+
70
+
```bash
71
+
# create migration after model changes
72
+
just backend migrate "description of change"
73
+
74
+
# apply migrations
75
+
just backend migrate-up
76
+
```
77
+
78
+
see [database migrations](./deployment/database-migrations.md) for the full workflow.
79
+
80
+
## conventions
81
+
82
+
### code style
83
+
84
+
- **type hints required** everywhere — Python and TypeScript
85
+
- **async everywhere** — never block the event loop. use `anyio`/`aiofiles`
86
+
- **lowercase aesthetic** in naming, docs, and commit messages
87
+
- **imports at the top** of files — only defer imports to break circular dependencies
88
+
- **keep it simple** — MVP over perfection
89
+
90
+
### python
91
+
92
+
- use `uv` for everything (never `pip`)
93
+
- use `uv run` to execute scripts and tools
94
+
- prefer walrus operator (`:=`) for assign-and-check patterns
95
+
- inline pass-through intermediate variables into constructor calls
96
+
97
+
### frontend
98
+
99
+
- SvelteKit with **Svelte 5 Runes** — use `$state`, `$derived`, `$effect`
100
+
- see [state management](./frontend/state-management.md) for patterns
101
+
102
+
### ATProto
103
+
104
+
- NSIDs are environment-aware via settings (`fm.plyr.dev` for dev, `fm.plyr` for prod) — never hardcode them
105
+
- session IDs live in HttpOnly cookies — never use `localStorage` for auth
106
+
107
+
## useful commands
108
+
109
+
```bash
110
+
# development
111
+
just backend run # start backend
112
+
just frontend run # start frontend
113
+
just backend test # run tests
114
+
just backend lint # lint python
115
+
just frontend check # lint svelte
116
+
117
+
# database
118
+
just backend migrate "msg" # create migration
119
+
just backend migrate-up # apply migrations
120
+
121
+
# infrastructure
122
+
just dev-services # start redis (docker)
123
+
just dev-services-down # stop redis
124
+
just tunnel # expose backend via ngrok
125
+
```
126
+
127
+
## project structure
128
+
129
+
```
130
+
plyr.fm/
131
+
├── backend/src/backend/
132
+
│ ├── api/ # public endpoints
133
+
│ ├── _internal/ # auth, PDS, uploads
134
+
│ ├── models/ # SQLAlchemy schemas
135
+
│ ├── storage/ # R2 and filesystem
136
+
│ └── utilities/ # config, helpers
137
+
├── frontend/src/
138
+
│ ├── routes/ # pages (+page.svelte, +page.server.ts)
139
+
│ └── lib/ # components & state (.svelte.ts)
140
+
├── services/
141
+
│ ├── transcoder/ # audio transcoding (Rust)
142
+
│ ├── moderation/ # content moderation (Rust)
143
+
│ └── clap/ # ML embeddings (Python, Modal)
144
+
├── scripts/ # admin scripts (uv run scripts/...)
145
+
├── docs/ # architecture & guides
146
+
└── STATUS.md # living status document
147
+
```
148
+
149
+
## further reading
150
+
151
+
- [local development setup](./local-development/setup.md) — full environment config and troubleshooting
152
+
- [backend configuration](./backend/configuration.md) — settings and environment variables
153
+
- [state management](./frontend/state-management.md) — Svelte 5 runes patterns
154
+
- [deployment environments](./deployment/environments.md) — staging vs production
155
+
- [tools](./tools/) — logfire, neon, pdsx, and other dev tools
+3
-1
docs/deployment/database-migrations.md
+3
-1
docs/deployment/database-migrations.md
+13
-1
docs/deployment/environments.md
+13
-1
docs/deployment/environments.md
···
1
-
# environment separation strategy
1
+
---
2
+
title: "environment separation strategy"
3
+
---
2
4
3
5
plyr.fm uses a simple three-tier deployment strategy: development → staging → production.
4
6
···
108
110
- production branch: `main`
109
111
- production environment: `PUBLIC_API_URL=https://api-stg.plyr.fm`
110
112
- custom domain: `stg.plyr.fm`
113
+
114
+
### docs
115
+
116
+
**plyr-fm-docs**:
117
+
- framework: astro (starlight)
118
+
- deployed via GHA workflow (`.github/workflows/deploy-docs.yml`) using `wrangler pages deploy`
119
+
- triggers on push to `main` when `docs/**` or `docs-site/**` change
120
+
- build command: `cd docs-site && bun install && bun run build`
121
+
- build output: `docs-site/dist`
122
+
- custom domain: `docs.plyr.fm`
111
123
112
124
### secrets management
113
125
+3
-1
docs/frontend/data-loading.md
+3
-1
docs/frontend/data-loading.md
+3
-1
docs/frontend/design-tokens.md
+3
-1
docs/frontend/design-tokens.md
+3
-1
docs/frontend/keyboard-shortcuts.md
+3
-1
docs/frontend/keyboard-shortcuts.md
+3
-1
docs/frontend/portals.md
+3
-1
docs/frontend/portals.md
+3
-1
docs/frontend/queue.md
+3
-1
docs/frontend/queue.md
+3
-1
docs/frontend/redirect-after-login.md
+3
-1
docs/frontend/redirect-after-login.md
+3
-1
docs/frontend/search.md
+3
-1
docs/frontend/search.md
+3
-1
docs/frontend/state-management.md
+3
-1
docs/frontend/state-management.md
+3
-1
docs/frontend/toast-notifications.md
+3
-1
docs/frontend/toast-notifications.md
+15
docs/index.md
+15
docs/index.md
···
1
+
---
2
+
title: plyr.fm docs
3
+
description: documentation for plyr.fm — audio streaming on ATProto
4
+
template: splash
5
+
hero:
6
+
title: plyr.fm docs
7
+
tagline: audio streaming on ATProto
8
+
actions:
9
+
- text: get started
10
+
link: /local-development/setup/
11
+
icon: right-arrow
12
+
- text: contributing
13
+
link: /contributing/
14
+
variant: minimal
15
+
---
+3
-1
docs/legal/meetings/2026-01-02-notes.md
+3
-1
docs/legal/meetings/2026-01-02-notes.md
+3
-1
docs/legal/meetings/2026-01-03-initial.md
+3
-1
docs/legal/meetings/2026-01-03-initial.md
+3
-1
docs/legal/privacy.md
+3
-1
docs/legal/privacy.md
+4
-2
docs/legal/questions.md
+4
-2
docs/legal/questions.md
+3
-1
docs/legal/terms.md
+3
-1
docs/legal/terms.md
+3
-1
docs/lexicons/overview.md
+3
-1
docs/lexicons/overview.md
+3
-1
docs/local-development/setup.md
+3
-1
docs/local-development/setup.md
+3
-1
docs/moderation/atproto-labeler.md
+3
-1
docs/moderation/atproto-labeler.md
+3
-1
docs/moderation/copyright-detection.md
+3
-1
docs/moderation/copyright-detection.md
+3
-1
docs/moderation/overview.md
+3
-1
docs/moderation/overview.md
+3
-1
docs/moderation/sensitive-content.md
+3
-1
docs/moderation/sensitive-content.md
+3
-1
docs/offboarding.md
+3
-1
docs/offboarding.md
+3
-1
docs/rate-limiting.md
+3
-1
docs/rate-limiting.md
+3
-1
docs/research/2025-12-18-moderation-cleanup.md
+3
-1
docs/research/2025-12-18-moderation-cleanup.md
+3
-1
docs/research/2025-12-19-beartype.md
+3
-1
docs/research/2025-12-19-beartype.md
+3
-1
docs/research/2025-12-20-atprotofans-paywall-integration.md
+3
-1
docs/research/2025-12-20-atprotofans-paywall-integration.md
+3
-1
docs/research/2025-12-20-moderation-architecture-overhaul.md
+3
-1
docs/research/2025-12-20-moderation-architecture-overhaul.md
+3
-1
docs/research/2025-12-20-supporter-gated-content-architecture.md
+3
-1
docs/research/2025-12-20-supporter-gated-content-architecture.md
+3
-1
docs/research/2026-01-01-atproto-oauth-permission-sets.md
+3
-1
docs/research/2026-01-01-atproto-oauth-permission-sets.md
+3
-1
docs/research/2026-01-03-multi-account-experience.md
+3
-1
docs/research/2026-01-03-multi-account-experience.md
+3
-1
docs/research/2026-01-29-atproto-media-service-patterns.md
+3
-1
docs/research/2026-01-29-atproto-media-service-patterns.md
+3
-1
docs/research/2026-01-29-pds-blob-storage.md
+3
-1
docs/research/2026-01-29-pds-blob-storage.md
+3
-1
docs/research/2026-02-28-redirect-after-login-ux.md
+3
-1
docs/research/2026-02-28-redirect-after-login-ux.md
+3
-1
docs/runbooks/README.md
+3
-1
docs/runbooks/README.md
+3
-1
docs/runbooks/connection-pool-exhaustion.md
+3
-1
docs/runbooks/connection-pool-exhaustion.md
+3
-1
docs/security.md
+3
-1
docs/security.md
+3
-1
docs/testing/README.md
+3
-1
docs/testing/README.md
+3
-1
docs/testing/integration-tests.md
+3
-1
docs/testing/integration-tests.md
+3
-1
docs/tools/logfire.md
+3
-1
docs/tools/logfire.md
+3
-1
docs/tools/neon.md
+3
-1
docs/tools/neon.md
···
1
-
# neon mcp guide for plyr.fm
1
+
---
2
+
title: "neon mcp guide for plyr.fm"
3
+
---
2
4
3
5
the [neon mcp server](https://github.com/neondatabase/mcp-server-neon) provides tools for interacting with neon postgres databases through the model context protocol. this guide covers read-only operations useful for inspecting and debugging plyr.fm's database.
4
6
+3
-1
docs/tools/pdsx.md
+3
-1
docs/tools/pdsx.md
+3
-1
docs/tools/plyrfm.md
+3
-1
docs/tools/plyrfm.md
+3
-1
docs/tools/status-maintenance.md
+3
-1
docs/tools/status-maintenance.md
+3
-1
docs/tools/tap.md
+3
-1
docs/tools/tap.md
+1
justfile
+1
justfile
+4
-4
loq.toml
+4
-4
loq.toml
···
87
87
88
88
[[rules]]
89
89
path = "docs/authentication.md"
90
-
max_lines = 627
90
+
max_lines = 631
91
91
92
92
[[rules]]
93
93
path = "docs/backend/liked-tracks.md"
94
-
max_lines = 503
94
+
max_lines = 507
95
95
96
96
[[rules]]
97
97
path = "docs/deployment/database-migrations.md"
98
-
max_lines = 629
98
+
max_lines = 633
99
99
100
100
[[rules]]
101
101
path = "docs/tools/neon.md"
102
-
max_lines = 519
102
+
max_lines = 523
103
103
104
104
[[rules]]
105
105
path = "frontend/src/lib/components/AddToMenu.svelte"