Node is needed only for these targets, never for the Go build or make check.
- commit
- 1115a181d7cc930954d03d73c983845dfd8fff86
- parent
- e71388b932b1a0b0d94f047b3bf944d06f1b1fe6
- author
- Dami <dami.etoile@gmail.com>
- kind
- build risk score 0.8 of 3, Jev's estimate
| M | Makefile | 20 | ++++++++++- |
| M | docs/ | 1 | + |
| A | docs/ | 60 | ++++++++++++++++++++++++++++++ |
| M | docs/ | 4 | ++- |
@@ -7,7 +7,7 @@ GHOSTTY_SRC := $(DEPS)/ghostty-src
77 GHOSTTY_OUT := $(DEPS)/ghostty88 GHOSTTY_STAMP := $(GHOSTTY_OUT)/.built-$(GHOSTTY_COMMIT)99 10-10+1111 1212 build:1313 CGO_ENABLED=0 go build -o bin/012 ./cmd/012@@ -123,6 +123,24 @@ demos: build
123123 demos/out/media/$$d.gif || exit 1; done124124 @ls -l demos/out/media125125 126+# The docs site (website/): Docusaurus over docs/, built into127+# website/build. Needs Node 20.11+ and npm; nothing else in the build or128+# make check does. The build fails on a broken link or anchor. SITE_URL129+# sets the address canonical links and the sitemap use. Node's warning130+# that localStorage has no backing file is about the build's own process,131+# which never stores anything. See docs/contributing/site.md.132+SITE_NODE := NODE_OPTIONS=--disable-warning=ExperimentalWarning133+134+site: site-deps135+ cd website && $(SITE_NODE) npm run build136+137+site-serve: site-deps138+ cd website && $(SITE_NODE) npm run start139+140+site-deps:141+ @command -v npm >/dev/null || { echo "the site needs Node 20.11+ and npm"; exit 1; }142+ cd website && npm ci143+126144 libghostty: $(GHOSTTY_STAMP)127145 128146 # The commit matches the one pinned by go.mitchellh.com/libghostty.@@ -17,5 +17,6 @@ in [CLAUDE.md](../../CLAUDE.md), then:
1717 | [Bounds of support](limits.md) | Measured bounds and known bottlenecks |1818 | [Observability](observability.md) | Event logs, OTLP export, DuckDB queries, the local telemetry stack |1919 | [Releasing](releasing.md) | The release checklist and `make dist` |20+| [The docs site](site.md) | Building and previewing the Docusaurus site over these docs |2021 2122 Plans are in the [roadmap](../../ROADMAP.md).@@ -0,0 +1,60 @@
1+---2+title: "The docs site"3+sidebar_position: 94+---5+6+# The docs site7+8+`website/` builds these docs into a static site with9+[Docusaurus](https://docusaurus.io). It reads `docs/` where it is, so a10+page is written once and reads the same on GitHub and on the site. It is11+the only part of the repository that needs Node: `make build`,12+`make check` and the Go toolchain never touch it.13+14+```sh15+make site # install from website/package-lock.json, build into website/build16+make site-serve # a dev server on http://localhost:3000 that reloads as docs change17+```18+19+Both need Node 20.11 or later and npm. `npm ci` installs exactly what20+the lockfile pins, with install scripts off (no dependency needs one).21+To look at the built site as a static host serves it, run22+`npm run serve` in `website/` after `make site`. `SITE_URL` sets the23+address canonical links and the sitemap use (`SITE_URL=https://... make24+site`); the site sits at the root of its host.25+26+## The build is a docs check27+28+`make site` fails on a link to a page that doesn't exist, an anchor no29+heading makes, a missing image or two pages at one address. It checks30+the same links `scripts/doccheck` does, as the site resolves them, so a31+page that passes `make lint` but breaks on the site shows up here.32+33+## How the docs become pages34+35+- Pages are Markdown as GitHub reads it (`markdown.format: 'detect'`):36+ `.md` files are CommonMark, so `<`, `{` and HTML comments are text and37+ markup rather than MDX. A page that needs components would be `.mdx`.38+- Each folder's `README.md` is its category's page (`/docs/sheets/`),39+ and the sidebar is generated from the tree: `_category_.json` for40+ folders, `title` and `sidebar_position` for pages41+ ([Docs](testing.md#docs) has the rules the tree follows).42+- Images in `docs/media/` are bundled from the pages that show them.43+- A relative link that leaves `docs/` (the roadmap, `CLAUDE.md`)44+ becomes a link to the file on GitHub45+ (`website/src/remark/repo-links.ts`).46+- The generated pages, [Functions](../reference/functions.md) and47+ [Configuration](../reference/config.md), are pages like any other.48+- Search is local: `@easyops-cn/docusaurus-search-local` builds an index49+ at build time, and nothing is sent to a service.50+51+## The look52+53+The landing page (`website/src/pages/index.tsx`) is drawn as a 01254+screen: a control panel with the mode indicator, the recording in an55+overlay frame, the features as cells of a sheet (the one under the56+pointer shows its entry in the control panel), and a status line. The57+colors in `website/src/css/custom.css` are the reference palettes of the58+golden screens, given the roles the app gives them: cyan where you are,59+bright black header bands, blue links and selection. Headings and chrome60+are IBM Plex Mono, body text IBM Plex Sans, both bundled with the site.@@ -14,6 +14,7 @@ make oracle # compare formulas and number formats with excelize
1414 make e2e # run the real binary in a terminal emulator (needs Zig and pkg-config)1515 make screens # rewrite the golden screens and build the review gallery1616 make stress # benchmarks on synthetic and real data (see limits.md)17+make site # build the docs site, failing on broken links (needs Node; see site.md)1718 ```1819 1920 ## Unit tests@@ -122,7 +123,8 @@ reads on GitHub and builds with Docusaurus as it is:
122123 in `docs/media/`.123124 124125 A new page goes in the folder a reader would look in, with front matter,125-and a line in the folder's README.126+and a line in the folder's README. `make site` builds them into the127+[docs site](site.md) and fails on any link or anchor it can't resolve.126128 127129 `make lint` runs `scripts/doclint`, which flags wording that narrates128130 history (see [CLAUDE.md](../../CLAUDE.md)), and `scripts/doccheck`, which