Vibecode GitBook
track this build5 phases, 10 steps, beginner friendly0%KINDA · weekend project
A docs site from Markdown with search, versioning and a custom domain is a weekend with Docusaurus or Starlight, and many teams already do it for free. The visual editor for non-engineers and the AI assistant over your docs are what $65 buys, and the editor is the part a weekend does not produce.
the project pack5 files · written for this build, step by step
You are building a lean indie version of GitBook. Create the following project files first, then implement the application by following them. Keep the files updated as decisions change. Do not collapse this into a single README or prompt. ===== README.md ===== # GitBook · indie build A documentation site from Markdown in a repo: Starlight for the site, Pagefind for search, versions and redirects from your old URLs, an edit-in-browser path that opens a pull request with a preview deploy, and a feedback widget. The visual editor and AI assistant stay with GitBook; the docs come home. Estimated effort: **weekend**. Work `BUILD_PLAN.md` top to bottom · every phase ends in a check that has to pass before the next one starts. ## Stack | Part | Choice | Why | | --- | --- | --- | | Framework | Astro with Starlight | documentation-shaped out of the box | | Search | Pagefind at build time | static, no service | | Hosting | A static host with preview deploys | the PR flow depends on previews | ## Before you start Have every one of these ready. The plan assumes them from step one. - [ ] **Node.js 22 or newer** · free - Why: Everything in this build runs on it: the server, the scripts, the tests. - Get it: Download the LTS installer from nodejs.org, or install with your package manager (brew install node, or nvm install 22). Restart the terminal afterwards. - Verify: node --version prints v22 or higher - [ ] **A terminal and a code editor** · free - Why: Every step below is a command you type or a file you edit. - Get it: VS Code (code.visualstudio.com), Cursor or Zed. Open a folder for the project and use the editor's built-in terminal. - Verify: You can open a folder and run a command in its terminal - [ ] **Git** · free - Why: History for your code, and the way most hosts deploy. - Get it: Install from git-scm.com or with your package manager, then run git init in the project folder once it exists. - Verify: git --version prints a version - [ ] **Your existing docs as Markdown** · free - Why: Phase 1 migrates real pages. - Get it: GitBook: enable Git Sync to a repo, or export pages one by one. Note every current URL for the redirect map. - [ ] **A static host with preview deployments** · free - Why: Phase 4's edit flow shows a preview per pull request. - Get it: Cloudflare Pages or Netlify connected to the repository. - [ ] **A domain or subdomain** (optional) · roughly $10 a year, or free on an existing domain - Why: docs.yourdomain.com - Get it: Register at Cloudflare Registrar, Porkbun or Namecheap, or use a subdomain of one you already own. You add one DNS record in the deploy phase. - [ ] **Where feedback goes** · free - Why: Phase 5 adds a widget; it needs a destination. - Get it: A tiny endpoint (see the Formspree entry on this site) or a hosted form. ## Quick start ```sh npm create astro@latest docs -- --template starlight --install --git cd docs ``` Then copy `.env.example` to `.env` and fill in the values it documents. ## Honest limits This build deliberately does not replace: - The block editor, the AI assistant, in-browser review workflow. - the block-based visual editor for non-developers - the AI assistant over your docs - change requests and review workflow in the browser - analytics and feedback built in If one of those is essential to you, that is the reason to keep paying for GitBook, and the README should say so rather than pretend. ===== BRIEF.md ===== # Build brief · GitBook The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins. Build me a documentation site to replace GitBook. Build it in phases, in the order below. Do not write the whole thing in one pass. Finish a phase, run its "Done when" check, fix what fails, and only then start the next phase. ### Stack (fixed, do not substitute) - Astro with Starlight. Markdown and MDX in a repo. Pagefind for search at build time. Static output on your domain. ### Phase 1 · The site Build: Starlight configured with your sidebar, a landing page, three real pages migrated from the current docs, and a working build. Broken internal links fail the build. Done when: the site builds, navigates, and a deliberately broken link makes the build fail with the page named. Do not build yet: search, versions, editor. ### Phase 2 · Search and structure Build: Pagefind search, a table of contents per page, tabs and callout components, and an OpenAPI page if you have an API. Done when: search finds a term inside a code block and the API page renders from the spec. ### Phase 3 · Versions and redirects Build: versioned docs folders with a version switcher, and a redirects file so old GitBook URLs land on the right page. Done when: every old URL from your GitBook sitemap resolves to a page or an explicit redirect. ### Phase 4 · Editing for non-engineers Build: an edit-this-page link that opens the file in the repo's web editor with a pull request flow, plus a preview deployment per PR. This is the honest substitute for the visual editor: a browser form that creates a PR. Done when: someone with no local setup edits a page in the browser and a preview link appears on the PR. ### Phase 5 · Deploy and measure Build: the static host config with the custom domain, a privacy-respecting pageview count, a feedback widget that stores to a small endpoint, and the README. Done when: docs are live on your domain and a feedback submission lands. ### Out of scope (and why) - The block editor, the AI assistant, in-browser review workflow. That is why GitBook costs $65 and the PR flow costs nothing. ### README must contain - How a non-engineer edits a page, step by step. - The redirect map from the old URLs. ===== AGENTS.md ===== # Agent instructions · GitBook indie build - Read `README.md` and `BUILD_PLAN.md` before writing code. The stack is fixed: Astro with Starlight, Pagefind at build time, A static host with preview deploys. Do not substitute. - Work one phase at a time, in order. Do not start a phase until every "Done when" item of the previous one passes. - Prefer the fewest moving parts that satisfy the step. No frameworks, services or dependencies the plan does not name. - Secrets live in `.env`, never in source or logs. Keep `.env.example` current when a variable is introduced. - Do not invent cryptography, security guarantees, APIs or compliance claims. - Add a focused test for every destructive, security-sensitive or data-loss path the plan names. - Run the project checks before declaring a phase complete, and record any deliberate shortcut in the README under "Tradeoffs". ===== BUILD_PLAN.md ===== # Build plan · GitBook A documentation site from Markdown in a repo: Starlight for the site, Pagefind for search, versions and redirects from your old URLs, an edit-in-browser path that opens a pull request with a preview deploy, and a feedback widget. The visual editor and AI assistant stay with GitBook; the docs come home. Phases are in dependency order. Each ends in a "Done when" list; treat an unticked item as a blocker, not a note. ## Phase 1 · The site Starlight with your sidebar and three real pages; broken links fail the build. ### Steps 1. Create the Starlight project and migrate three pages ```sh npm create astro@latest docs -- --template starlight --install --git cd docs ``` 2. Enable link checking so a broken internal link fails the build ```sh npm install starlight-links-validator ``` ### Done when - [ ] The site builds and navigates - [ ] A deliberately broken link fails the build naming the page ## Phase 2 · Search and structure Pagefind, TOC, tabs, callouts, an OpenAPI page if you have one. ### Steps 1. Confirm Pagefind indexes code blocks; add tabs and asides 2. Add an OpenAPI page from your spec if applicable ```sh npm install starlight-openapi ``` ### Done when - [ ] Search finds a term inside a code block - [ ] The API page renders from the spec ## Phase 3 · Versions and redirects Version switcher and every old URL resolving. ### Steps 1. Versioned folders with a switcher 2. A redirects file mapping every old GitBook URL Files: `public/_redirects` ### Done when - [ ] Every old URL from your sitemap resolves to a page or an explicit redirect ## Phase 4 · Editing for non-engineers Edit in the browser, get a PR and a preview link. ### Steps 1. Edit-this-page links opening the file in the repo host's web editor 2. Preview deployments per pull request ### Done when - [ ] Someone with no local setup edits a page in the browser and a preview link appears on the PR ## Phase 5 · Deploy and measure Live on your domain with a feedback widget and a pageview count. ### Steps 1. Custom domain and a privacy-respecting pageview count 2. A feedback widget posting to FEEDBACK_ENDPOINT; README with the non-engineer edit steps and the redirect map Files: `README.md` ### Done when - [ ] Docs are live on your domain - [ ] A feedback submission lands ## Not in this build - The block editor, the AI assistant, in-browser review workflow. ## After v1, if you want it - An AI search box over your own docs behind your own key - Localized versions ===== .env.example ===== # Copy to .env and fill in. Never commit .env; this file documents it. # Required. Canonical base. SITE_URL=https://docs.yourdomain.com # Optional. Where the widget posts. FEEDBACK_ENDPOINT=https://forms.yourdomain.com/f/docs
You are building a lean indie version of GitBook. Create the following project files first, then implement the application by following them. Keep the files updated as decisions change. Do not collapse this into a single README or prompt. ===== README.md ===== # GitBook · indie build A documentation site from Markdown in a repo: Starlight for the site, Pagefind for search, versions and redirects from your old URLs, an edit-in-browser path that opens a pull request with a preview deploy, and a feedback widget. The visual editor and AI assistant stay with GitBook; the docs come home. Estimated effort: **weekend**. Work `BUILD_PLAN.md` top to bottom · every phase ends in a check that has to pass before the next one starts. ## Stack | Part | Choice | Why | | --- | --- | --- | | Framework | Astro with Starlight | documentation-shaped out of the box | | Search | Pagefind at build time | static, no service | | Hosting | A static host with preview deploys | the PR flow depends on previews | ## Before you start Have every one of these ready. The plan assumes them from step one. - [ ] **Node.js 22 or newer** · free - Why: Everything in this build runs on it: the server, the scripts, the tests. - Get it: Download the LTS installer from nodejs.org, or install with your package manager (brew install node, or nvm install 22). Restart the terminal afterwards. - Verify: node --version prints v22 or higher - [ ] **A terminal and a code editor** · free - Why: Every step below is a command you type or a file you edit. - Get it: VS Code (code.visualstudio.com), Cursor or Zed. Open a folder for the project and use the editor's built-in terminal. - Verify: You can open a folder and run a command in its terminal - [ ] **Git** · free - Why: History for your code, and the way most hosts deploy. - Get it: Install from git-scm.com or with your package manager, then run git init in the project folder once it exists. - Verify: git --version prints a version - [ ] **Your existing docs as Markdown** · free - Why: Phase 1 migrates real pages. - Get it: GitBook: enable Git Sync to a repo, or export pages one by one. Note every current URL for the redirect map. - [ ] **A static host with preview deployments** · free - Why: Phase 4's edit flow shows a preview per pull request. - Get it: Cloudflare Pages or Netlify connected to the repository. - [ ] **A domain or subdomain** (optional) · roughly $10 a year, or free on an existing domain - Why: docs.yourdomain.com - Get it: Register at Cloudflare Registrar, Porkbun or Namecheap, or use a subdomain of one you already own. You add one DNS record in the deploy phase. - [ ] **Where feedback goes** · free - Why: Phase 5 adds a widget; it needs a destination. - Get it: A tiny endpoint (see the Formspree entry on this site) or a hosted form. ## Quick start ```sh npm create astro@latest docs -- --template starlight --install --git cd docs ``` Then copy `.env.example` to `.env` and fill in the values it documents. ## Honest limits This build deliberately does not replace: - The block editor, the AI assistant, in-browser review workflow. - the block-based visual editor for non-developers - the AI assistant over your docs - change requests and review workflow in the browser - analytics and feedback built in If one of those is essential to you, that is the reason to keep paying for GitBook, and the README should say so rather than pretend. ===== BRIEF.md ===== # Build brief · GitBook The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins. Build me a documentation site to replace GitBook. Build it in phases, in the order below. Do not write the whole thing in one pass. Finish a phase, run its "Done when" check, fix what fails, and only then start the next phase. ### Stack (fixed, do not substitute) - Astro with Starlight. Markdown and MDX in a repo. Pagefind for search at build time. Static output on your domain. ### Phase 1 · The site Build: Starlight configured with your sidebar, a landing page, three real pages migrated from the current docs, and a working build. Broken internal links fail the build. Done when: the site builds, navigates, and a deliberately broken link makes the build fail with the page named. Do not build yet: search, versions, editor. ### Phase 2 · Search and structure Build: Pagefind search, a table of contents per page, tabs and callout components, and an OpenAPI page if you have an API. Done when: search finds a term inside a code block and the API page renders from the spec. ### Phase 3 · Versions and redirects Build: versioned docs folders with a version switcher, and a redirects file so old GitBook URLs land on the right page. Done when: every old URL from your GitBook sitemap resolves to a page or an explicit redirect. ### Phase 4 · Editing for non-engineers Build: an edit-this-page link that opens the file in the repo's web editor with a pull request flow, plus a preview deployment per PR. This is the honest substitute for the visual editor: a browser form that creates a PR. Done when: someone with no local setup edits a page in the browser and a preview link appears on the PR. ### Phase 5 · Deploy and measure Build: the static host config with the custom domain, a privacy-respecting pageview count, a feedback widget that stores to a small endpoint, and the README. Done when: docs are live on your domain and a feedback submission lands. ### Out of scope (and why) - The block editor, the AI assistant, in-browser review workflow. That is why GitBook costs $65 and the PR flow costs nothing. ### README must contain - How a non-engineer edits a page, step by step. - The redirect map from the old URLs. ===== AGENTS.md ===== # Agent instructions · GitBook indie build - Read `README.md` and `BUILD_PLAN.md` before writing code. The stack is fixed: Astro with Starlight, Pagefind at build time, A static host with preview deploys. Do not substitute. - Work one phase at a time, in order. Do not start a phase until every "Done when" item of the previous one passes. - Prefer the fewest moving parts that satisfy the step. No frameworks, services or dependencies the plan does not name. - Secrets live in `.env`, never in source or logs. Keep `.env.example` current when a variable is introduced. - Do not invent cryptography, security guarantees, APIs or compliance claims. - Add a focused test for every destructive, security-sensitive or data-loss path the plan names. - Run the project checks before declaring a phase complete, and record any deliberate shortcut in the README under "Tradeoffs". ===== BUILD_PLAN.md ===== # Build plan · GitBook A documentation site from Markdown in a repo: Starlight for the site, Pagefind for search, versions and redirects from your old URLs, an edit-in-browser path that opens a pull request with a preview deploy, and a feedback widget. The visual editor and AI assistant stay with GitBook; the docs come home. Phases are in dependency order. Each ends in a "Done when" list; treat an unticked item as a blocker, not a note. ## Phase 1 · The site Starlight with your sidebar and three real pages; broken links fail the build. ### Steps 1. Create the Starlight project and migrate three pages ```sh npm create astro@latest docs -- --template starlight --install --git cd docs ``` 2. Enable link checking so a broken internal link fails the build ```sh npm install starlight-links-validator ``` ### Done when - [ ] The site builds and navigates - [ ] A deliberately broken link fails the build naming the page ## Phase 2 · Search and structure Pagefind, TOC, tabs, callouts, an OpenAPI page if you have one. ### Steps 1. Confirm Pagefind indexes code blocks; add tabs and asides 2. Add an OpenAPI page from your spec if applicable ```sh npm install starlight-openapi ``` ### Done when - [ ] Search finds a term inside a code block - [ ] The API page renders from the spec ## Phase 3 · Versions and redirects Version switcher and every old URL resolving. ### Steps 1. Versioned folders with a switcher 2. A redirects file mapping every old GitBook URL Files: `public/_redirects` ### Done when - [ ] Every old URL from your sitemap resolves to a page or an explicit redirect ## Phase 4 · Editing for non-engineers Edit in the browser, get a PR and a preview link. ### Steps 1. Edit-this-page links opening the file in the repo host's web editor 2. Preview deployments per pull request ### Done when - [ ] Someone with no local setup edits a page in the browser and a preview link appears on the PR ## Phase 5 · Deploy and measure Live on your domain with a feedback widget and a pageview count. ### Steps 1. Custom domain and a privacy-respecting pageview count 2. A feedback widget posting to FEEDBACK_ENDPOINT; README with the non-engineer edit steps and the redirect map Files: `README.md` ### Done when - [ ] Docs are live on your domain - [ ] A feedback submission lands ## Not in this build - The block editor, the AI assistant, in-browser review workflow. ## After v1, if you want it - An AI search box over your own docs behind your own key - Localized versions ===== .env.example ===== # Copy to .env and fill in. Never commit .env; this file documents it. # Required. Canonical base. SITE_URL=https://docs.yourdomain.com # Optional. Where the widget posts. FEEDBACK_ENDPOINT=https://forms.yourdomain.com/f/docs
You are building a production product version of GitBook. Create the following project files first, then implement the application by following them. Keep the files updated as decisions change. Do not collapse this into a single README or prompt. ===== PRODUCT.md ===== # GitBook · product brief ## Problem A docs site from Markdown with search, versioning and a custom domain is a weekend with Docusaurus or Starlight, and many teams already do it for free. The visual editor for non-engineers and the AI assistant over your docs are what $65 buys, and the editor is the part a weekend does not produce. ## Product outcome Docs that live with the code, editable by anyone through a PR, searchable without a service. ## Target user A builder who needs a maintainable product foundation, not a one-off demo. ## Required capabilities - a static host and domain - a repo ## Explicit non-goals for v1 - The block editor, the AI assistant, in-browser review workflow. - the block-based visual editor for non-developers - the AI assistant over your docs - change requests and review workflow in the browser - analytics and feedback built in ## Success criteria - Every old URL redirects - A non-engineer completed an edit via PR ===== BRIEF.md ===== # Build brief · GitBook The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins. Build me a documentation site to replace GitBook. Build it in phases, in the order below. Do not write the whole thing in one pass. Finish a phase, run its "Done when" check, fix what fails, and only then start the next phase. ### Stack (fixed, do not substitute) - Astro with Starlight. Markdown and MDX in a repo. Pagefind for search at build time. Static output on your domain. ### Phase 1 · The site Build: Starlight configured with your sidebar, a landing page, three real pages migrated from the current docs, and a working build. Broken internal links fail the build. Done when: the site builds, navigates, and a deliberately broken link makes the build fail with the page named. Do not build yet: search, versions, editor. ### Phase 2 · Search and structure Build: Pagefind search, a table of contents per page, tabs and callout components, and an OpenAPI page if you have an API. Done when: search finds a term inside a code block and the API page renders from the spec. ### Phase 3 · Versions and redirects Build: versioned docs folders with a version switcher, and a redirects file so old GitBook URLs land on the right page. Done when: every old URL from your GitBook sitemap resolves to a page or an explicit redirect. ### Phase 4 · Editing for non-engineers Build: an edit-this-page link that opens the file in the repo's web editor with a pull request flow, plus a preview deployment per PR. This is the honest substitute for the visual editor: a browser form that creates a PR. Done when: someone with no local setup edits a page in the browser and a preview link appears on the PR. ### Phase 5 · Deploy and measure Build: the static host config with the custom domain, a privacy-respecting pageview count, a feedback widget that stores to a small endpoint, and the README. Done when: docs are live on your domain and a feedback submission lands. ### Out of scope (and why) - The block editor, the AI assistant, in-browser review workflow. That is why GitBook costs $65 and the PR flow costs nothing. ### README must contain - How a non-engineer edits a page, step by step. - The redirect map from the old URLs. ===== ARCHITECTURE.md ===== # Architecture · GitBook ## Stack | Part | Choice | Why | | --- | --- | --- | | Framework | Astro with Starlight | documentation-shaped out of the box | | Search | Pagefind at build time | static, no service | | Hosting | A static host with preview deploys | the PR flow depends on previews | ## Modules Each module has one owner concern and a documented way to replace it. | Module | Owns | How to replace it | | --- | --- | --- | | Content | Markdown and the sidebar | Any Markdown | | Site | Starlight | Docusaurus against the same files | | Edit flow | PR and previews | A CMS writing to the repo later | | Feedback | the widget | Any endpoint | ## Configuration Every runtime setting is an environment variable documented in `.env.example`, validated at startup, with a safe local default wherever one exists. - `SITE_URL` · required · Canonical base. - `FEEDBACK_ENDPOINT` · optional · Where the widget posts. ## Production baseline - Security: least privilege, input validation at every boundary, secret redaction in logs, rate limits on abuse-prone paths, no invented security primitives. - Data: explicit schema and migrations, transactional writes where integrity matters, backup and restore procedures that have been exercised. - Integrations: adapters around third-party providers, idempotent webhook or job processing, bounded retries, timeouts. - Observability: structured logs with request or operation ids, an error-tracking hook, and health and readiness checks where a server exists. - Quality: unit tests for domain rules, integration tests at module boundaries, one end-to-end test of the critical path. ## Decision records For each dependency in the stack table, keep a short note: why it was chosen, its failure mode, and how it is replaced. Do not add infrastructure until a requirement in `PRODUCT.md` justifies it. ===== AGENTS.md ===== # Agent instructions · GitBook product build - Read `PRODUCT.md` and `ARCHITECTURE.md` before changing code. The stack is fixed: Astro with Starlight, Pagefind at build time, A static host with preview deploys. - Implement milestone by milestone from `MILESTONES.md`; keep each change reviewable and leave the application runnable at every commit. - Treat authentication, payments, encryption, imports, webhooks and destructive actions as high-risk boundaries when present. - Never invent cryptography or silently weaken a requirement to make a check pass. - Put every external service behind an interface with a deterministic fake for tests. - Add migrations and rollback or recovery notes for every persistent data change. - Log useful operational context without credentials, tokens, passwords or personal data. - Update documentation and run every check before completing a milestone. ===== MILESTONES.md ===== # Delivery milestones · GitBook Estimated effort: **weekend** for the indie phases; the production-only milestones add the trust and operability layer. ## M1 · The site Starlight with your sidebar and three real pages; broken links fail the build. ### Steps 1. Create the Starlight project and migrate three pages ```sh npm create astro@latest docs -- --template starlight --install --git cd docs ``` 2. Enable link checking so a broken internal link fails the build ```sh npm install starlight-links-validator ``` ### Done when - [ ] The site builds and navigates - [ ] A deliberately broken link fails the build naming the page ## M2 · Search and structure Pagefind, TOC, tabs, callouts, an OpenAPI page if you have one. ### Steps 1. Confirm Pagefind indexes code blocks; add tabs and asides 2. Add an OpenAPI page from your spec if applicable ```sh npm install starlight-openapi ``` ### Done when - [ ] Search finds a term inside a code block - [ ] The API page renders from the spec ## M3 · Versions and redirects Version switcher and every old URL resolving. ### Steps 1. Versioned folders with a switcher 2. A redirects file mapping every old GitBook URL Files: `public/_redirects` ### Done when - [ ] Every old URL from your sitemap resolves to a page or an explicit redirect ## M4 · Editing for non-engineers Edit in the browser, get a PR and a preview link. ### Steps 1. Edit-this-page links opening the file in the repo host's web editor 2. Preview deployments per pull request ### Done when - [ ] Someone with no local setup edits a page in the browser and a preview link appears on the PR ## M5 · Deploy and measure Live on your domain with a feedback widget and a pageview count. ### Steps 1. Custom domain and a privacy-respecting pageview count 2. A feedback widget posting to FEEDBACK_ENDPOINT; README with the non-engineer edit steps and the redirect map Files: `README.md` ### Done when - [ ] Docs are live on your domain - [ ] A feedback submission lands ## M6 · Operate (production only) Link checks on a schedule and a broken-link budget. ### Steps 1. A weekly CI job checking external links 2. Uptime on the docs domain ### Done when - [ ] A dead external link is reported within a week ===== OPERATIONS.md ===== # Operations · GitBook ## Backup The repo. ## Restore Redeploy. Do a restore drill before the first real user, and write the date here when it passes. ## Monitoring Uptime and link checks. ## Incident checklist Revert with git. 1. Contain the issue without destroying evidence or user data. 2. Record the timeline and affected scope. 3. Rotate exposed secrets and revoke compromised sessions or credentials. 4. Restore from a verified backup when needed. 5. Document the root cause, the remediation and the regression test. ## Release gate - [ ] Every old URL redirects - [ ] A non-engineer completed an edit via PR ## Launch constraint Do not market omitted GitBook capabilities as implemented. The non-goals in `PRODUCT.md` remain user-visible limitations until they are deliberately delivered. ===== .env.example ===== # Copy to .env and fill in. Never commit .env; this file documents it. # Required. Canonical base. SITE_URL=https://docs.yourdomain.com # Optional. Where the widget posts. FEEDBACK_ENDPOINT=https://forms.yourdomain.com/f/docs
README.md
# GitBook · indie build A documentation site from Markdown in a repo: Starlight for the site, Pagefind for search, versions and redirects from your old URLs, an edit-in-browser path that opens a pull request with a preview deploy, and a feedback widget. The visual editor and AI assistant stay with GitBook; the docs come home. Estimated effort: **weekend**. Work `BUILD_PLAN.md` top to bottom · every phase ends in a check that has to pass before the next one starts. ## Stack | Part | Choice | Why | | --- | --- | --- | | Framework | Astro with Starlight | documentation-shaped out of the box | | Search | Pagefind at build time | static, no service | | Hosting | A static host with preview deploys | the PR flow depends on previews | ## Before you start Have every one of these ready. The plan assumes them from step one. - [ ] **Node.js 22 or newer** · free - Why: Everything in this build runs on it: the server, the scripts, the tests. - Get it: Download the LTS installer from nodejs.org, or install with your package manager (brew install node, or nvm install 22). Restart the terminal afterwards. - Verify: node --version prints v22 or higher - [ ] **A terminal and a code editor** · free - Why: Every step below is a command you type or a file you edit. - Get it: VS Code (code.visualstudio.com), Cursor or Zed. Open a folder for the project and use the editor's built-in terminal. - Verify: You can open a folder and run a command in its terminal - [ ] **Git** · free - Why: History for your code, and the way most hosts deploy. - Get it: Install from git-scm.com or with your package manager, then run git init in the project folder once it exists. - Verify: git --version prints a version - [ ] **Your existing docs as Markdown** · free - Why: Phase 1 migrates real pages. - Get it: GitBook: enable Git Sync to a repo, or export pages one by one. Note every current URL for the redirect map. - [ ] **A static host with preview deployments** · free - Why: Phase 4's edit flow shows a preview per pull request. - Get it: Cloudflare Pages or Netlify connected to the repository. - [ ] **A domain or subdomain** (optional) · roughly $10 a year, or free on an existing domain - Why: docs.yourdomain.com - Get it: Register at Cloudflare Registrar, Porkbun or Namecheap, or use a subdomain of one you already own. You add one DNS record in the deploy phase. - [ ] **Where feedback goes** · free - Why: Phase 5 adds a widget; it needs a destination. - Get it: A tiny endpoint (see the Formspree entry on this site) or a hosted form. ## Quick start ```sh npm create astro@latest docs -- --template starlight --install --git cd docs ``` Then copy `.env.example` to `.env` and fill in the values it documents. ## Honest limits This build deliberately does not replace: - The block editor, the AI assistant, in-browser review workflow. - the block-based visual editor for non-developers - the AI assistant over your docs - change requests and review workflow in the browser - analytics and feedback built in If one of those is essential to you, that is the reason to keep paying for GitBook, and the README should say so rather than pretend.
BRIEF.md
# Build brief · GitBook The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins. Build me a documentation site to replace GitBook. Build it in phases, in the order below. Do not write the whole thing in one pass. Finish a phase, run its "Done when" check, fix what fails, and only then start the next phase. ### Stack (fixed, do not substitute) - Astro with Starlight. Markdown and MDX in a repo. Pagefind for search at build time. Static output on your domain. ### Phase 1 · The site Build: Starlight configured with your sidebar, a landing page, three real pages migrated from the current docs, and a working build. Broken internal links fail the build. Done when: the site builds, navigates, and a deliberately broken link makes the build fail with the page named. Do not build yet: search, versions, editor. ### Phase 2 · Search and structure Build: Pagefind search, a table of contents per page, tabs and callout components, and an OpenAPI page if you have an API. Done when: search finds a term inside a code block and the API page renders from the spec. ### Phase 3 · Versions and redirects Build: versioned docs folders with a version switcher, and a redirects file so old GitBook URLs land on the right page. Done when: every old URL from your GitBook sitemap resolves to a page or an explicit redirect. ### Phase 4 · Editing for non-engineers Build: an edit-this-page link that opens the file in the repo's web editor with a pull request flow, plus a preview deployment per PR. This is the honest substitute for the visual editor: a browser form that creates a PR. Done when: someone with no local setup edits a page in the browser and a preview link appears on the PR. ### Phase 5 · Deploy and measure Build: the static host config with the custom domain, a privacy-respecting pageview count, a feedback widget that stores to a small endpoint, and the README. Done when: docs are live on your domain and a feedback submission lands. ### Out of scope (and why) - The block editor, the AI assistant, in-browser review workflow. That is why GitBook costs $65 and the PR flow costs nothing. ### README must contain - How a non-engineer edits a page, step by step. - The redirect map from the old URLs.
AGENTS.md
# Agent instructions · GitBook indie build - Read `README.md` and `BUILD_PLAN.md` before writing code. The stack is fixed: Astro with Starlight, Pagefind at build time, A static host with preview deploys. Do not substitute. - Work one phase at a time, in order. Do not start a phase until every "Done when" item of the previous one passes. - Prefer the fewest moving parts that satisfy the step. No frameworks, services or dependencies the plan does not name. - Secrets live in `.env`, never in source or logs. Keep `.env.example` current when a variable is introduced. - Do not invent cryptography, security guarantees, APIs or compliance claims. - Add a focused test for every destructive, security-sensitive or data-loss path the plan names. - Run the project checks before declaring a phase complete, and record any deliberate shortcut in the README under "Tradeoffs".
BUILD_PLAN.md
# Build plan · GitBook A documentation site from Markdown in a repo: Starlight for the site, Pagefind for search, versions and redirects from your old URLs, an edit-in-browser path that opens a pull request with a preview deploy, and a feedback widget. The visual editor and AI assistant stay with GitBook; the docs come home. Phases are in dependency order. Each ends in a "Done when" list; treat an unticked item as a blocker, not a note. ## Phase 1 · The site Starlight with your sidebar and three real pages; broken links fail the build. ### Steps 1. Create the Starlight project and migrate three pages ```sh npm create astro@latest docs -- --template starlight --install --git cd docs ``` 2. Enable link checking so a broken internal link fails the build ```sh npm install starlight-links-validator ``` ### Done when - [ ] The site builds and navigates - [ ] A deliberately broken link fails the build naming the page ## Phase 2 · Search and structure Pagefind, TOC, tabs, callouts, an OpenAPI page if you have one. ### Steps 1. Confirm Pagefind indexes code blocks; add tabs and asides 2. Add an OpenAPI page from your spec if applicable ```sh npm install starlight-openapi ``` ### Done when - [ ] Search finds a term inside a code block - [ ] The API page renders from the spec ## Phase 3 · Versions and redirects Version switcher and every old URL resolving. ### Steps 1. Versioned folders with a switcher 2. A redirects file mapping every old GitBook URL Files: `public/_redirects` ### Done when - [ ] Every old URL from your sitemap resolves to a page or an explicit redirect ## Phase 4 · Editing for non-engineers Edit in the browser, get a PR and a preview link. ### Steps 1. Edit-this-page links opening the file in the repo host's web editor 2. Preview deployments per pull request ### Done when - [ ] Someone with no local setup edits a page in the browser and a preview link appears on the PR ## Phase 5 · Deploy and measure Live on your domain with a feedback widget and a pageview count. ### Steps 1. Custom domain and a privacy-respecting pageview count 2. A feedback widget posting to FEEDBACK_ENDPOINT; README with the non-engineer edit steps and the redirect map Files: `README.md` ### Done when - [ ] Docs are live on your domain - [ ] A feedback submission lands ## Not in this build - The block editor, the AI assistant, in-browser review workflow. ## After v1, if you want it - An AI search box over your own docs behind your own key - Localized versions
.env.example
# Copy to .env and fill in. Never commit .env; this file documents it. # Required. Canonical base. SITE_URL=https://docs.yourdomain.com # Optional. Where the widget posts. FEEDBACK_ENDPOINT=https://forms.yourdomain.com/f/docs
PRODUCT.md
# GitBook · product brief ## Problem A docs site from Markdown with search, versioning and a custom domain is a weekend with Docusaurus or Starlight, and many teams already do it for free. The visual editor for non-engineers and the AI assistant over your docs are what $65 buys, and the editor is the part a weekend does not produce. ## Product outcome Docs that live with the code, editable by anyone through a PR, searchable without a service. ## Target user A builder who needs a maintainable product foundation, not a one-off demo. ## Required capabilities - a static host and domain - a repo ## Explicit non-goals for v1 - The block editor, the AI assistant, in-browser review workflow. - the block-based visual editor for non-developers - the AI assistant over your docs - change requests and review workflow in the browser - analytics and feedback built in ## Success criteria - Every old URL redirects - A non-engineer completed an edit via PR
BRIEF.md
# Build brief · GitBook The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins. Build me a documentation site to replace GitBook. Build it in phases, in the order below. Do not write the whole thing in one pass. Finish a phase, run its "Done when" check, fix what fails, and only then start the next phase. ### Stack (fixed, do not substitute) - Astro with Starlight. Markdown and MDX in a repo. Pagefind for search at build time. Static output on your domain. ### Phase 1 · The site Build: Starlight configured with your sidebar, a landing page, three real pages migrated from the current docs, and a working build. Broken internal links fail the build. Done when: the site builds, navigates, and a deliberately broken link makes the build fail with the page named. Do not build yet: search, versions, editor. ### Phase 2 · Search and structure Build: Pagefind search, a table of contents per page, tabs and callout components, and an OpenAPI page if you have an API. Done when: search finds a term inside a code block and the API page renders from the spec. ### Phase 3 · Versions and redirects Build: versioned docs folders with a version switcher, and a redirects file so old GitBook URLs land on the right page. Done when: every old URL from your GitBook sitemap resolves to a page or an explicit redirect. ### Phase 4 · Editing for non-engineers Build: an edit-this-page link that opens the file in the repo's web editor with a pull request flow, plus a preview deployment per PR. This is the honest substitute for the visual editor: a browser form that creates a PR. Done when: someone with no local setup edits a page in the browser and a preview link appears on the PR. ### Phase 5 · Deploy and measure Build: the static host config with the custom domain, a privacy-respecting pageview count, a feedback widget that stores to a small endpoint, and the README. Done when: docs are live on your domain and a feedback submission lands. ### Out of scope (and why) - The block editor, the AI assistant, in-browser review workflow. That is why GitBook costs $65 and the PR flow costs nothing. ### README must contain - How a non-engineer edits a page, step by step. - The redirect map from the old URLs.
ARCHITECTURE.md
# Architecture · GitBook ## Stack | Part | Choice | Why | | --- | --- | --- | | Framework | Astro with Starlight | documentation-shaped out of the box | | Search | Pagefind at build time | static, no service | | Hosting | A static host with preview deploys | the PR flow depends on previews | ## Modules Each module has one owner concern and a documented way to replace it. | Module | Owns | How to replace it | | --- | --- | --- | | Content | Markdown and the sidebar | Any Markdown | | Site | Starlight | Docusaurus against the same files | | Edit flow | PR and previews | A CMS writing to the repo later | | Feedback | the widget | Any endpoint | ## Configuration Every runtime setting is an environment variable documented in `.env.example`, validated at startup, with a safe local default wherever one exists. - `SITE_URL` · required · Canonical base. - `FEEDBACK_ENDPOINT` · optional · Where the widget posts. ## Production baseline - Security: least privilege, input validation at every boundary, secret redaction in logs, rate limits on abuse-prone paths, no invented security primitives. - Data: explicit schema and migrations, transactional writes where integrity matters, backup and restore procedures that have been exercised. - Integrations: adapters around third-party providers, idempotent webhook or job processing, bounded retries, timeouts. - Observability: structured logs with request or operation ids, an error-tracking hook, and health and readiness checks where a server exists. - Quality: unit tests for domain rules, integration tests at module boundaries, one end-to-end test of the critical path. ## Decision records For each dependency in the stack table, keep a short note: why it was chosen, its failure mode, and how it is replaced. Do not add infrastructure until a requirement in `PRODUCT.md` justifies it.
AGENTS.md
# Agent instructions · GitBook product build - Read `PRODUCT.md` and `ARCHITECTURE.md` before changing code. The stack is fixed: Astro with Starlight, Pagefind at build time, A static host with preview deploys. - Implement milestone by milestone from `MILESTONES.md`; keep each change reviewable and leave the application runnable at every commit. - Treat authentication, payments, encryption, imports, webhooks and destructive actions as high-risk boundaries when present. - Never invent cryptography or silently weaken a requirement to make a check pass. - Put every external service behind an interface with a deterministic fake for tests. - Add migrations and rollback or recovery notes for every persistent data change. - Log useful operational context without credentials, tokens, passwords or personal data. - Update documentation and run every check before completing a milestone.
MILESTONES.md
# Delivery milestones · GitBook Estimated effort: **weekend** for the indie phases; the production-only milestones add the trust and operability layer. ## M1 · The site Starlight with your sidebar and three real pages; broken links fail the build. ### Steps 1. Create the Starlight project and migrate three pages ```sh npm create astro@latest docs -- --template starlight --install --git cd docs ``` 2. Enable link checking so a broken internal link fails the build ```sh npm install starlight-links-validator ``` ### Done when - [ ] The site builds and navigates - [ ] A deliberately broken link fails the build naming the page ## M2 · Search and structure Pagefind, TOC, tabs, callouts, an OpenAPI page if you have one. ### Steps 1. Confirm Pagefind indexes code blocks; add tabs and asides 2. Add an OpenAPI page from your spec if applicable ```sh npm install starlight-openapi ``` ### Done when - [ ] Search finds a term inside a code block - [ ] The API page renders from the spec ## M3 · Versions and redirects Version switcher and every old URL resolving. ### Steps 1. Versioned folders with a switcher 2. A redirects file mapping every old GitBook URL Files: `public/_redirects` ### Done when - [ ] Every old URL from your sitemap resolves to a page or an explicit redirect ## M4 · Editing for non-engineers Edit in the browser, get a PR and a preview link. ### Steps 1. Edit-this-page links opening the file in the repo host's web editor 2. Preview deployments per pull request ### Done when - [ ] Someone with no local setup edits a page in the browser and a preview link appears on the PR ## M5 · Deploy and measure Live on your domain with a feedback widget and a pageview count. ### Steps 1. Custom domain and a privacy-respecting pageview count 2. A feedback widget posting to FEEDBACK_ENDPOINT; README with the non-engineer edit steps and the redirect map Files: `README.md` ### Done when - [ ] Docs are live on your domain - [ ] A feedback submission lands ## M6 · Operate (production only) Link checks on a schedule and a broken-link budget. ### Steps 1. A weekly CI job checking external links 2. Uptime on the docs domain ### Done when - [ ] A dead external link is reported within a week
OPERATIONS.md
# Operations · GitBook ## Backup The repo. ## Restore Redeploy. Do a restore drill before the first real user, and write the date here when it passes. ## Monitoring Uptime and link checks. ## Incident checklist Revert with git. 1. Contain the issue without destroying evidence or user data. 2. Record the timeline and affected scope. 3. Rotate exposed secrets and revoke compromised sessions or credentials. 4. Restore from a verified backup when needed. 5. Document the root cause, the remediation and the regression test. ## Release gate - [ ] Every old URL redirects - [ ] A non-engineer completed an edit via PR ## Launch constraint Do not market omitted GitBook capabilities as implemented. The non-goals in `PRODUCT.md` remain user-visible limitations until they are deliberately delivered.
.env.example
# Copy to .env and fill in. Never commit .env; this file documents it. # Required. Canonical base. SITE_URL=https://docs.yourdomain.com # Optional. Where the widget posts. FEEDBACK_ENDPOINT=https://forms.yourdomain.com/f/docs
$ choose a build depth, inspect the files, then open the complete pack in your agent
Because the people who should write docs do not open pull requests, and $65 a month is cheaper than making them.
xthe block-based visual editor for non-developers
xthe AI assistant over your docs
xchange requests and review workflow in the browser
xanalytics and feedback built in
share on X ↗"I just replaced GitBook ($65/mo) with one prompt"
GitBook pricing
premium$65/mo · monthly per site · $780/yr
free tierThe free plan publishes a docs site with Git sync but no custom domain or AI search.
verified 2026-09-04 · source ↗
Is GitBook free?
The free plan publishes a docs site with Git sync but no custom domain or AI search. Paid is Premium at $65/mo (checked 2026-09-04).
Vibecode GitBook
Kinda. The core of GitBook is buildable in a weekend with the prompt on this page, but there are real gaps: the block-based visual editor for non-developers, the AI assistant over your docs. Read the honest list above before committing.
How much does GitBook cost?
GitBook costs about $65/month (Premium, checked 2026-09-04), which is $780 per year.
What do I lose by replacing GitBook?
Honestly: the block-based visual editor for non-developers; the AI assistant over your docs; change requests and review workflow in the browser; analytics and feedback built in. If any of those are load-bearing for you, keep paying.
Is there an open-source alternative to GitBook?
Yes: Starlight (documentation framework on Astro), Docusaurus (documentation site generator). Using prior art is also vibecoding; the prompt is for when you want it exactly your way.