Skip to content

Add automated docs sync pipeline from forge repo#14

Merged
initializ-mk merged 2 commits intomainfrom
docs/sync-pipeline
Apr 20, 2026
Merged

Add automated docs sync pipeline from forge repo#14
initializ-mk merged 2 commits intomainfrom
docs/sync-pipeline

Conversation

@initializ-mk
Copy link
Copy Markdown
Contributor

Summary

  • Add scripts/sync-docs.ts that fetches docs from initializ/forge via GitHub API, parses YAML frontmatter, rewrites relative links to Astro routes, and generates docs-manifest.json
  • Add scripts/sync-docs-stub.ts for generating placeholder docs during local dev without GitHub access
  • Remove manually-maintained docs from git — they are now generated at build time via npm run sync:docs

How it works

  1. Forge repo has restructured docs in subdirectories (getting-started/, core-concepts/, etc.) with YAML frontmatter — see forge PR branch
  2. sync-docs.ts fetches the git tree, downloads each .md, validates frontmatter, rewrites links, and writes to src/content/docs/
  3. sync:docs runs first in the fetch pipeline so docs exist before Astro processes other pages
  4. Stub script generates minimal placeholders for astro dev without network access

Changes

  • scripts/sync-docs.ts — main sync script (fetches, parses, rewrites, writes)
  • scripts/sync-docs-stub.ts — dev stub generator (36 placeholder pages)
  • package.json — add sync:docs, sync:docs:stub; sync:docs runs first in fetch
  • .gitignore — exclude synced docs directories and manifest
  • Removed 36 manually-maintained doc files from git tracking

Test plan

  • npx tsx scripts/sync-docs-stub.ts generates 36 placeholder docs
  • npx tsx scripts/sync-docs.ts fetches docs (once forge branch is merged)
  • npm run build succeeds with synced/stub docs
  • Synced files are in .gitignore, not tracked in git
  • docs-manifest.json generated with correct section counts

- Create scripts/sync-docs.ts: fetches docs from initializ/forge
  via GitHub API, parses frontmatter, rewrites links to Astro
  routes, generates docs-manifest.json
- Create scripts/sync-docs-stub.ts: generates placeholder docs
  for astro dev without GitHub access
- Add sync:docs and sync:docs:stub scripts to package.json;
  sync:docs runs first in the fetch pipeline
- Remove manually-maintained docs from git tracking (now
  generated at build time via sync:docs)
- Update .gitignore to exclude synced docs directories
Triggers on repository_dispatch from forge repo (docs-updated
event) or manual workflow_dispatch. Runs sync-docs.ts, commits
any changes, and pushes — which triggers Cloudflare Pages
auto-deploy.
@initializ-mk initializ-mk merged commit 73d321c into main Apr 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant