Skip to content

Commit a889b84

Browse files
qwerzlqwerzl
authored
feat(build): aggregate docs from source repos (pilot: spectrum-ts) (#103)
Make the docs repo an aggregator. `scripts/sync-docs` assembles a single template tree (.vellum-src/) from local docs-src/ plus per-source docs pulled from their SDK repo's docs-site/ at the git tag matching the installed package version, with a `local` fallback during migration. `scripts/build-nav` generates docs.json from docs.base.json (committed skeleton) + each source's nav.json fragment. The spectrum-ts pilot runs via the local fallback, so rendered .mdx, llms*.txt, and docs.json are byte-identical to before. docs.json is now generated (untracked); deploy-dist force-adds it and derives the mdx list from .vellum-src. ENG-1742
1 parent d7b20ef commit a889b84

10 files changed

Lines changed: 444 additions & 107 deletions

File tree

‎.github/workflows/deploy-dist.yml‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,14 +40,25 @@ jobs:
4040

4141
- name: Generate docs from Vellum templates
4242
run: pnpm docs:generate
43+
# sync-docs pulls per-source docs at the tag matching the installed
44+
# package version. While a source still has a `local` fallback it stays
45+
# offline; once a source is git-only, widen the app token's
46+
# `repositories:` above to include that source repo so the clone can auth.
47+
env:
48+
GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
4349

4450
- name: Push to dist branch
4551
run: |
4652
git config user.name "github-actions[bot]"
4753
git config user.email "github-actions[bot]@users.noreply.github.com"
4854
49-
# Force-add all Vellum-generated files (gitignored, but needed on dist)
50-
git add -f $(find docs-src -name '*.vel' | sed 's|^docs-src/||;s|\.vel$||')
55+
# Force-add the generated navigation (gitignored, but needed on dist)
56+
git add -f docs.json
57+
58+
# Force-add all Vellum-generated files (gitignored, but needed on dist).
59+
# Template list comes from the assembled tree (.vellum-src), not docs-src,
60+
# since sources may be pulled from other repos.
61+
git add -f $(find .vellum-src -name '*.vel' | sed 's|^.vellum-src/||;s|\.vel$||')
5162
5263
# Force-add custom llms.txt generator output (also gitignored)
5364
git add -f llms.txt llms-full.txt llms-*.txt

‎.gitignore‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,13 @@ node_modules
33

44
.pnpm-store
55

6-
# Vellum generated output (built from docs-src/*.vel templates)
6+
# Aggregated template tree, assembled by scripts/sync-docs from docs-src/ + source repos
7+
.vellum-src/
8+
9+
# Navigation, generated by scripts/build-nav from docs.base.json + source nav fragments
10+
/docs.json
11+
12+
# Vellum generated output (built from .vellum-src/*.vel templates)
713
advanced-kits/imessage/*.mdx
814
advanced-kits/whatsapp/*.mdx
915
opensource/*.mdx

‎README.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,20 @@
22

33
The documentation site at [photon.codes](https://photon.codes/), built with [Mintlify](https://mintlify.com/) and driven by [vellum](https://github.com/photon-hq/vellum). Vellum extracts type information from installed npm packages and renders `.mdx.vel` templates into the `.mdx` files Mintlify ships.
44

5+
This repo is an **aggregator**: some doc areas are authored here in [`docs-src/`](docs-src/), and others are authored in the SDK repos they document and pulled in at build time (see [Where docs live](#where-docs-live)).
6+
7+
## Where docs live
8+
9+
`scripts/sync-docs` assembles a single template tree (`.vellum-src/`, gitignored) before vellum runs, from two places:
10+
11+
- **Local** — most areas still live in [`docs-src/`](docs-src/) in this repo.
12+
- **Source repos** — areas listed in [`scripts/sources.json`](scripts/sources.json) are pulled from their SDK repo's `docs-site/` directory, at the git tag matching the installed package version (so prose stays aligned with the types vellum extracts). Edit those in the SDK repo, not here. Until a source repo has its `docs-site/`, sync falls back to the `local` path in the manifest, so the pilot keeps building offline.
13+
14+
Navigation works the same way: [`docs.json`](docs.json) is **generated** by `scripts/build-nav` from [`docs.base.json`](docs.base.json) (the site skeleton) plus a `nav.json` fragment contributed by each source. Don't edit `docs.json` directly — edit `docs.base.json` or the fragment.
15+
516
## How to edit
617

7-
1. **Edit the source, not the output.** Sources live in [`docs-src/`](docs-src/) as `.mdx.vel` files. The rendered `.mdx` files at the repo root are build artifacts — gitignored on `main`, only present on the `dist` branch. Don't edit them directly; they get overwritten on every deploy.
18+
1. **Edit the source, not the output.** Sources are `.mdx.vel` files in [`docs-src/`](docs-src/) (this repo) or a source repo's `docs-site/`. The rendered `.mdx` files and `docs.json` at the repo root are build artifacts — gitignored on `main`, only present on the `dist` branch. Don't edit them directly; they get overwritten on every deploy.
819

920
2. **Render and preview locally:**
1021

‎docs-src/spectrum-ts/nav.json‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
{
2+
"source": "spectrum-ts",
3+
"groups": [
4+
{
5+
"group": "Get started",
6+
"pages": [
7+
"spectrum-ts/introduction",
8+
"spectrum-ts/getting-started"
9+
]
10+
},
11+
{
12+
"group": "Core concepts",
13+
"pages": [
14+
"spectrum-ts/messages",
15+
"spectrum-ts/spaces-and-users",
16+
"spectrum-ts/reactions-and-replies",
17+
"spectrum-ts/platform-narrowing",
18+
"spectrum-ts/webhooks"
19+
]
20+
},
21+
{
22+
"group": "Content",
23+
"pages": [
24+
"spectrum-ts/content",
25+
"spectrum-ts/content/text",
26+
"spectrum-ts/content/markdown",
27+
"spectrum-ts/content/attachments",
28+
"spectrum-ts/content/voice",
29+
"spectrum-ts/content/contacts",
30+
"spectrum-ts/content/rich-links",
31+
"spectrum-ts/content/app",
32+
"spectrum-ts/content/polls",
33+
"spectrum-ts/content/groups",
34+
"spectrum-ts/content/custom",
35+
"spectrum-ts/content/replies",
36+
"spectrum-ts/content/edits",
37+
"spectrum-ts/content/unsend",
38+
"spectrum-ts/content/typing-indicators",
39+
"spectrum-ts/content/rename",
40+
"spectrum-ts/content/avatar",
41+
"spectrum-ts/content/composing-content"
42+
]
43+
},
44+
{
45+
"group": "Providers",
46+
"pages": [
47+
"spectrum-ts/providers",
48+
{
49+
"group": "iMessage",
50+
"icon": "comment",
51+
"root": "spectrum-ts/providers/imessage",
52+
"pages": [
53+
"spectrum-ts/providers/imessage/connection-and-routing",
54+
"spectrum-ts/providers/imessage/messaging-features"
55+
]
56+
},
57+
{
58+
"group": "Terminal",
59+
"icon": "terminal",
60+
"root": "spectrum-ts/providers/terminal",
61+
"pages": [
62+
"spectrum-ts/providers/terminal/setup-and-usage",
63+
"spectrum-ts/providers/terminal/interactions"
64+
]
65+
},
66+
{
67+
"group": "WhatsApp Business",
68+
"icon": "whatsapp",
69+
"root": "spectrum-ts/providers/whatsapp-business",
70+
"pages": [
71+
"spectrum-ts/providers/whatsapp-business/setup",
72+
"spectrum-ts/providers/whatsapp-business/conversations"
73+
]
74+
},
75+
{
76+
"group": "Telegram",
77+
"icon": "paper-plane",
78+
"root": "spectrum-ts/providers/telegram",
79+
"pages": [
80+
"spectrum-ts/providers/telegram/setup",
81+
"spectrum-ts/providers/telegram/conversations-and-features"
82+
]
83+
},
84+
{
85+
"group": "Slack",
86+
"icon": "hash",
87+
"root": "spectrum-ts/providers/slack",
88+
"pages": [
89+
"spectrum-ts/providers/slack/setup",
90+
"spectrum-ts/providers/slack/conversations-and-events"
91+
]
92+
}
93+
]
94+
},
95+
{
96+
"group": "Advanced",
97+
"pages": [
98+
"spectrum-ts/custom-events-and-lifecycle",
99+
"spectrum-ts/custom-platforms"
100+
]
101+
},
102+
{
103+
"group": "Troubleshooting",
104+
"pages": [
105+
"spectrum-ts/troubleshooting/imessage"
106+
]
107+
}
108+
]
109+
}

docs.json renamed to docs.base.json

Lines changed: 21 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -26,102 +26,24 @@
2626
"tab": "Spectrum",
2727
"groups": [
2828
{
29-
"group": "Get started",
30-
"pages": [
31-
"spectrum-ts/introduction",
32-
"spectrum-ts/getting-started"
33-
]
29+
"$source": "spectrum-ts",
30+
"group": "Get started"
3431
},
3532
{
36-
"group": "Core concepts",
37-
"pages": [
38-
"spectrum-ts/messages",
39-
"spectrum-ts/spaces-and-users",
40-
"spectrum-ts/reactions-and-replies",
41-
"spectrum-ts/platform-narrowing",
42-
"spectrum-ts/webhooks"
43-
]
33+
"$source": "spectrum-ts",
34+
"group": "Core concepts"
4435
},
4536
{
46-
"group": "Content",
47-
"pages": [
48-
"spectrum-ts/content",
49-
"spectrum-ts/content/text",
50-
"spectrum-ts/content/markdown",
51-
"spectrum-ts/content/attachments",
52-
"spectrum-ts/content/voice",
53-
"spectrum-ts/content/contacts",
54-
"spectrum-ts/content/rich-links",
55-
"spectrum-ts/content/app",
56-
"spectrum-ts/content/polls",
57-
"spectrum-ts/content/groups",
58-
"spectrum-ts/content/custom",
59-
"spectrum-ts/content/replies",
60-
"spectrum-ts/content/edits",
61-
"spectrum-ts/content/unsend",
62-
"spectrum-ts/content/typing-indicators",
63-
"spectrum-ts/content/rename",
64-
"spectrum-ts/content/avatar",
65-
"spectrum-ts/content/composing-content"
66-
]
37+
"$source": "spectrum-ts",
38+
"group": "Content"
6739
},
6840
{
69-
"group": "Providers",
70-
"pages": [
71-
"spectrum-ts/providers",
72-
{
73-
"group": "iMessage",
74-
"icon": "comment",
75-
"root": "spectrum-ts/providers/imessage",
76-
"pages": [
77-
"spectrum-ts/providers/imessage/connection-and-routing",
78-
"spectrum-ts/providers/imessage/messaging-features"
79-
]
80-
},
81-
{
82-
"group": "Terminal",
83-
"icon": "terminal",
84-
"root": "spectrum-ts/providers/terminal",
85-
"pages": [
86-
"spectrum-ts/providers/terminal/setup-and-usage",
87-
"spectrum-ts/providers/terminal/interactions"
88-
]
89-
},
90-
{
91-
"group": "WhatsApp Business",
92-
"icon": "whatsapp",
93-
"root": "spectrum-ts/providers/whatsapp-business",
94-
"pages": [
95-
"spectrum-ts/providers/whatsapp-business/setup",
96-
"spectrum-ts/providers/whatsapp-business/conversations"
97-
]
98-
},
99-
{
100-
"group": "Telegram",
101-
"icon": "paper-plane",
102-
"root": "spectrum-ts/providers/telegram",
103-
"pages": [
104-
"spectrum-ts/providers/telegram/setup",
105-
"spectrum-ts/providers/telegram/conversations-and-features"
106-
]
107-
},
108-
{
109-
"group": "Slack",
110-
"icon": "hash",
111-
"root": "spectrum-ts/providers/slack",
112-
"pages": [
113-
"spectrum-ts/providers/slack/setup",
114-
"spectrum-ts/providers/slack/conversations-and-events"
115-
]
116-
}
117-
]
41+
"$source": "spectrum-ts",
42+
"group": "Providers"
11843
},
11944
{
120-
"group": "Advanced",
121-
"pages": [
122-
"spectrum-ts/custom-events-and-lifecycle",
123-
"spectrum-ts/custom-platforms"
124-
]
45+
"$source": "spectrum-ts",
46+
"group": "Advanced"
12547
},
12648
{
12749
"group": "Integrations",
@@ -139,10 +61,8 @@
13961
]
14062
},
14163
{
142-
"group": "Troubleshooting",
143-
"pages": [
144-
"spectrum-ts/troubleshooting/imessage"
145-
]
64+
"$source": "spectrum-ts",
65+
"group": "Troubleshooting"
14666
}
14767
]
14868
},
@@ -298,15 +218,15 @@
298218
},
299219
"contextual": {
300220
"options": [
301-
"copy",
302-
"view",
303-
"chatgpt",
304-
"claude",
305-
"perplexity",
306-
"mcp",
307-
"cursor",
308-
"vscode"
309-
]
221+
"copy",
222+
"view",
223+
"chatgpt",
224+
"claude",
225+
"perplexity",
226+
"mcp",
227+
"cursor",
228+
"vscode"
229+
]
310230
},
311231
"footer": {
312232
"socials": {

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@
44
"private": true,
55
"packageManager": "pnpm@10.33.0",
66
"scripts": {
7-
"docs:generate": "vellum build && tsx scripts/llms-generator/index.ts",
7+
"docs:generate": "pnpm docs:sync && tsx scripts/build-nav/index.ts && vellum build && tsx scripts/llms-generator/index.ts",
8+
"docs:sync": "tsx scripts/sync-docs/index.ts",
89
"docs:llms": "tsx scripts/llms-generator/index.ts",
910
"lint": "eslint .",
1011
"lint:fix": "eslint . --fix",

0 commit comments

Comments
 (0)