a09975b95f
* Align Docusaurus config for monorepo, wire Algolia DocSearch (P6) Fixes projectName/editUrl/path references left over from the docs-unified repo split, adds trailingSlash for predictable CloudFront 404 handling, and wires an Algolia search block into themeConfig that's only included when credentials are present (Docusaurus's schema rejects an empty appId/apiKey, so this keeps builds green with or without them). Also fixes the sidebar/redirect generator scripts, which still pointed at the pre-rename docs/ directory instead of main/, and adds docs/Makefile, .env.local.example, and an updated README for local dev. * Wire OpenAPI generation to api/v4/source and add docs-ci.yaml (P7) Replaces build-openapi.mjs's custom YAML-merge implementation with a thin wrapper around the canonical `make -C api build` target, keeping only the MDX sanitization step (quote/autolink fixes) that docusaurus-plugin-openapi-docs needs. Adds a "prebuild" npm script so `npm run build` regenerates the spec automatically, and ignores the generated api/v4/html artifacts (narrow form, since ssr_template.hbs and static/favicon.ico under that path are committed). Also adds docs-ci.yaml as a path-scoped PR/master build+typecheck gate for the docs site, replacing the legacy `docs` repo's Sphinx-based ci.yml now that docs live in this monorepo. * Rename OpenAPI prebuild script for clarity "prebuild" is an npm lifecycle hook name (auto-runs before "npm run build"), not a descriptive name, so `npm run prebuild` didn't signal it's specifically about OpenAPI generation. Split it into "build:openapi" (the actual script, runnable directly and self-explanatory) with "prebuild" now just delegating to it, preserving the automatic pre-build trigger. * Regenerate sidebars automatically before dev/build (P7 fixup) documentation.generated.json and developers.generated.json are gitignored and nothing produced them on a fresh checkout, so both `npm start` and `npm run build` failed with MODULE_NOT_FOUND outside a working tree that happened to have stale copies lying around. Wire the sidebar generators into `prestart`/`prebuild` so they're always regenerated first. * Remove docs/site/.env.local.example There's a single Algolia DocSearch app for docs.mattermost.com; credentials aren't distributed to individual developers, so a per-dev .env.local workflow doesn't apply. Credentials are only ever injected in CI/CD via repository variables. Local builds/dev server run fine without them (the Algolia block in docusaurus.config.ts is conditional). * Wire OpenAPI doc generation into prestart/prebuild, drop unused Makefile docusaurus-plugin-openapi-docs requires a separate `docusaurus gen-api-docs` CLI step to populate docs/api/reference/ (gitignored) — nothing was invoking it, so a fresh checkout's npm start/build failed the same way the sidebar JSONs did. Split build:openapi into build:openapi:spec (slow, runs make -C api build) and build:openapi:docs (fast, generates MDX from the existing spec), and wire prestart to reuse an existing spec instead of rebuilding it every dev-server start. Also drops docs/Makefile: four of its five targets were pure passthroughs to npm scripts, unreferenced by CI or anything else, and there's no repo-wide `make -C <dir>` convention to fit into. Note: a duplicate-doc-id build failure (operationId `status` in the Playbooks OpenAPI spec colliding with the main API's `status` tag) is being fixed separately in mattermost-plugin-playbooks. * Fix stale docs/ reference in sidebar generator's error message The existence check still hardcoded "docs/" in its error text after SRC was repointed to main/. Use the SRC constant in the message so it can't drift out of sync with the actual path again. * remove code comment * Drop unused artifact upload from docs-ci.yaml Nothing consumes it: P9's docs-cd.yml will rebuild independently on push to master rather than downloading it via workflow_run (avoids workflow_run trigger footguns for an infrequent, cheap-enough rebuild), and P10's preview build always needs its own independent build anyway (bakes a per-PR BASE_URL). This was carried over from the old docs repo's ci.yml out of habit; that repo's own PR-time uploads had the same unused-artifact issue (only cd.yml's post-merge run ever consumed it). --------- Co-authored-by: Hanzo Dev <[email protected]>
4.2 KiB
Mattermost Documentation Site
Docusaurus workspace for docs.mattermost.com,
living in the mattermost/mattermost
monorepo at docs/site/.
Content layout
| Directory | Route | Description |
|---|---|---|
docs/main/ |
/ |
User and admin documentation |
docs/develop/ |
/developers |
Developer documentation |
docs/api/ |
/api |
API reference intro + generated OpenAPI pages |
Paths are relative to the repository root. The Docusaurus site reads them
via the relative paths ../main, ../develop, ../api (from docs/site/).
Prerequisites
- Node.js ≥ 20 — use
nvm useinsidedocs/site/to pick up.nvmrc - Go and
make(required only for the OpenAPI prebuild step — see below) - Vale ≥ 3 (for content linting)
Local development
cd docs/site
npm ci
npm start # dev server at http://localhost:3000
Sidebar generation
The documentation and developers sidebars are generated from the content
directories (sidebars/documentation.generated.json /
developers.generated.json, both gitignored) by npm run build:sidebars.
Docusaurus imports these files directly, so they must exist before
docusaurus start or docusaurus build runs — on a fresh checkout there's
no other source for them. This is wired automatically via the prestart and
prebuild npm lifecycle hooks, so plain npm start / npm run build just
work.
(sidebars/active-redirects.json, by contrast, is committed — it's
regenerated and checked in manually via node scripts/gen-active-redirects.mjs
when the legacy redirect map changes, not on every build.)
The API reference section (docs/api/reference/, also gitignored) has the
same requirement: docusaurus-plugin-openapi-docs needs docusaurus gen-api-docs mattermost run before it has any pages to render. prestart
handles this too — using the existing OpenAPI spec if present, only falling
back to the slow make -C api build spec rebuild if it's missing.
Full production build
The production build also includes an OpenAPI prebuild step (npm run build:openapi, wired to run automatically before npm run build via the
same prebuild hook) that invokes make -C api build. This requires Go and
takes ~2 minutes.
cd docs/site
npm ci
npm run build # runs build:sidebars + build:openapi (via prebuild), then Docusaurus build
To skip the OpenAPI rebuild during iterative content work:
cd docs/site
npm run build -- --no-minify # still runs build:sidebars + build:openapi first
If you need to bypass the prebuild step entirely (e.g., all generated artifacts already exist and are current), run:
cd docs/site
npm run docusaurus build # calls docusaurus directly, skips prebuild
Algolia search
There's a single Algolia DocSearch app for docs.mattermost.com — credentials
aren't distributed to individual developers. They're set as repository
variables (vars.ALGOLIA_APP_ID, vars.ALGOLIA_SEARCH_API_KEY) and injected
only in CI/CD. Local builds simply run without them: the site builds cleanly
and the search bar is omitted (see the conditional in
docusaurus.config.ts).
If you need to test search locally, export the same two variables in your
shell before running npm start/npm run build.
Scripts
| Command | Description |
|---|---|
npm start |
Dev server with hot reload (runs build:sidebars + build:openapi:docs first via prestart) |
npm run build |
Production build to build/ (runs build:sidebars + build:openapi first via prebuild) |
npm run build:sidebars |
Regenerate the documentation + developer sidebar JSON |
npm run build:openapi:spec |
Regenerate the OpenAPI spec only (slow — invokes make -C api build) |
npm run build:openapi:docs |
Regenerate the API reference MDX pages from the existing spec (fast) |
npm run build:openapi |
Full OpenAPI pipeline: spec then docs |
npm run serve |
Serve the build/ output locally |
npm run typecheck |
TypeScript type check |
node scripts/gen-active-redirects.mjs |
Regenerate legacy redirect map (committed to git; run manually when it changes) |
Content linting
vale main develop api