Skip to content

Latest commit

 

History

History
89 lines (62 loc) · 4.59 KB

README.md

File metadata and controls

89 lines (62 loc) · 4.59 KB

patch-it docs

Public developer documentation for patch-it, published at https://docs.patch-it.dev.

Built with Astro Starlight: the standard developer-docs layout (sidebar, page, "On this page", search, light/dark mode).

Write a page

Pages are Markdown files in src/content/docs/. The folder decides where a page appears in the sidebar:

Folder Sidebar section
get-started/ Get started (order set in astro.config.mjs)
guides/ Guides
configuration/ Configuration
supported-apis/ Supported APIs
api-reference/ API reference
resources/ Resources

Each page starts with frontmatter:

---
title: Page title
description: One sentence for search and link previews.
sidebar:
  order: 2
---

Use :::note, :::tip, :::caution and :::danger for callouts.

Keep internal details out of here: internal APIs, architecture and runbooks belong in the private developer-handbook repo.

The list of plugins

Supported APIs → All plugins shows every provider and source patch-it watches, grouped by category. The only list is the plugin registry in the public patch-it-plugins code; nothing here or there keeps one by hand. Each patch-it-plugins release attaches it as plugins.json.

  • npm run build and npm run dev first run scripts/sync-plugins.mjs (npm's prebuild / predev): it downloads https://github.com/patch-it-dev/patch-it-plugins/releases/latest/download/plugins.json (no token) and writes the list, one table per category, between <!-- plugins:start --> and <!-- plugins:end --> in the page.
  • Offline, GitHub down, or no asset: it prints a warning and writes "the list is temporarily unavailable" there instead, so the build never fails on it and never shows an old copy.
  • Don't commit a rendered list. The committed page holds the "unavailable" note; a local build leaves the rendered list as a diff in your working tree: discard it (git checkout src/content/docs/supported-apis/plugins.md).
  • Preview another list with PLUGINS_JSON_URL=<url or file:///path> npm run sync-plugins.
  • The site updates when it's rebuilt after a patch-it-plugins release.

llms.txt

The build also writes /llms.txt (an index of the docs for AI tools, in the llmstxt.org format) and /llms-full.txt (the text of those pages in one file). Both are generated from the pages (src/pages/llms*.txt.ts, src/llms.ts):

  • Summary and details come from the first paragraph and the rest of get-started/introduction.md.
  • Sections follow the sidebar (src/sidebar.mjs), pages in sidebar order.
  • Stubs are left out: a page is listed once it has at least 30 words besides the :::note[Coming soon] aside. Write the page and it shows up; there is no list to update.

The look

The docs wear the patch-it brand (the patch-it-brand repo), the same as patch-it.dev:

What Where
Colors (Dark default, Light) mapped onto Starlight's variables src/styles/custom.css
Wordmark in the header, with a "docs" tag src/assets/wordmark-plain-on-*.svg
Patchy on the home page src/assets/bot-on-*.svg
Code-block colors: the same themes as the CLI and editor src/themes/patch-it-*.json
Favicons, app icons, social image public/
IBM Plex Sans and Mono, self-hosted @fontsource/* in astro.config.mjs

When the brand changes, copy the new files over from patch-it-brand. Don't restyle the docs by hand.

Run locally

npm install
npm run dev      # http://localhost:4321
npm run build    # static site in dist/
npm start        # serves dist/ on $PORT (what Railway runs)

Reviews

Claude reviews each pull request once, when it's opened or marked ready (.github/workflows/claude-code-review.yml): the docs match what the CLI and the Action do, links resolve, nothing internal, the voice. PRs from forks get no secrets, so for those a maintainer comments @claude review and Claude reviews it read-only (it never runs a fork's code). Only maintainers can call @claude (claude.yml). Claude's review helps; a maintainer still decides.

Deploy (Railway)

  • Build command: npm run build
  • Start command: npm start
  • Custom domain: docs.patch-it.dev. In Railway → Settings → Public Networking → + Custom Domain, then add the CNAME and the _railway-verify TXT it shows in Cloudflare (CNAME proxied).

Brand

Colors, fonts and logo are in src/styles/custom.css, src/assets/logo.svg and public/favicon.svg. The orange accent is a placeholder until the brand color is final.