vibecodeit

Build GitBook

KINDAreplaces $65/mosaves $780/yrback to the verdict

0%0 of 17 items done

Saved on this device only. Tick prerequisites first, then work the phases in order · do not start one until the checks above it pass.

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 weekendthe files for this build are in the project pack

FrameworkAstro with StarlightSearchPagefind at build timeHostingA static host with preview deploys

Before step 1

Everything below is assumed from the first step. Tick each one when you actually have it, not when you plan to.

  1. installfree

    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. open ↗

    Verify node --version prints v22 or higher

  2. installfree

    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. open ↗

    Verify You can open a folder and run a command in its terminal

  3. installfree

    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. open ↗

    Verify git --version prints a version

  4. have readyfree

    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.

  5. free

    Why Phase 4's edit flow shows a preview per pull request.

    Get it Cloudflare Pages or Netlify connected to the repository. open ↗

  6. 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. open ↗

  7. decidefree

    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.

Environment variables

These go in a .env file the app reads at startup. The pack's .env.example is this table as a file · copy it, never commit the filled-in version.

VariableNeededExampleWhere the value comes from
SITE_URLrequiredhttps://docs.yourdomain.comCanonical base.
FEEDBACK_ENDPOINToptionalhttps://forms.yourdomain.com/f/docsWhere the widget posts.

The build, in order

  1. The site

    Starlight with your sidebar and three real pages; broken links fail the build.

    1. terminal
      npm create astro@latest docs -- --template starlight --install --git
cd docs
    2. terminal
      npm install starlight-links-validator
    done when · tick each as it passes
    next phase

  2. Search and structure

    Pagefind, TOC, tabs, callouts, an OpenAPI page if you have one.

    2. terminal
      npm install starlight-openapi
    done when · tick each as it passes
    next phase

  3. Versions and redirects

    Version switcher and every old URL resolving.

    2. Files public/_redirects

    done when · tick each as it passes
    next phase

  4. Editing for non-engineers

    Edit in the browser, get a PR and a preview link.

    done when · tick each as it passes
    next phase

  5. Deploy and measure

    Live on your domain with a feedback widget and a pageview count.

    2. Files README.md

    done when · tick each as it passes
    next phase
what this build does not replace
after v1, if you want it

Need the files? The project pack on the verdict page hands your agent the whole brief · more documents & pdfs.