Skip to content

README.md

Latest commit

 

History

History
120 lines (98 loc) · 5.41 KB

README.md

File metadata and controls

120 lines (98 loc) · 5.41 KB
Raw

mdbase.dev

Product website and developer documentation for mdbase, mdbase Connect, the runtime profiles, and conforming implementations.

Local development

pnpm install
pnpm sync:sources
pnpm dev

The source synchronizer reads sibling checkouts of mdbase-spec, mdbase-connect, mdbase-contracts, mdbase-rs, and mdbase by default. Override their paths with MDBASE_SPEC_DIR, MDBASE_CONNECT_DIR, MDBASE_CONTRACTS_DIR, MDBASE_RS_DIR, and MDBASE_TS_DIR. Check those checkouts out at the refs in site-sources.json to match production. The synchronized schemas, contracts and conformance data are generated and untracked (see .gitignore), so run the synchronizer before building. CI, deployment and the Connect release update all regenerate them from the pinned refs. To change what the site publishes, change site-sources.json.

Production build

Release checks require gh authentication and cosign; CI installs the pinned Cosign version used by the Connect release workflow.

pnpm sync:sources
pnpm check
pnpm build
(cd ../mdbase-spec/site && npm ci && npm run build)
pnpm import:spec
pnpm index:site
pnpm check:links

pnpm index:site builds the Pagefind index for the header's search dialog, then writes a Markdown copy of each page (index.md beside its index.html), /llms.txt and /llms-full.txt (scripts/build-llms.mjs). It runs after the specification import so the specification is included. Each page's <main> is used; headers, footers and documentation sidebars are excluded, as are pages marked noIndex and the archived specification.

The website repository owns the ecosystem pages and deployment cadence. The normative specification is built by mdbase-spec and imported under /spec/. The import preserves its content and section anchors, inserting them into the Astro specification shells (current and v0.2 archive). Those shells use the same BaseLayout, fonts, theme control, and documentation styles as /sdk/; the upstream site's header, scripts, and stylesheet are deliberately not imported. Run pnpm import:spec after building to populate these shells; pnpm dev alone shows the shell without the normative content. Connect schemas, theme roles, the homepage particle field, and implementation claims are synchronized from their canonical repositories. Generated assets remain traceable to the release artifacts they document.

The first-party contract catalog is built from the commit pinned in site-sources.json, then published as static files under /contracts/.

SDK guide example and API reference

examples/worklog is the app the SDK tutorial builds. The tutorial and the other SDK pages import their listings from its files, so a listing cannot drift from code that compiles. CI installs, type-checks and builds it.

cd examples/worklog
npm ci
npm run dev      # http://localhost:5173, against production mdbase
npm run build    # WORKLOG_ORIGIN=https://… sets the deployed origin

/sdk/api/ is rendered from src/data/sdk-api.json, which pnpm build:sdk-api reads out of the type declarations of the @mdbase-dev/sdk version the example installs. After changing that version, run npm install in examples/worklog, then pnpm build:sdk-api, and commit both. CI fails (pnpm check:sdk-api) when the committed file is stale.

Connect release updates

A published Connect desktop release dispatches its immutable tag to .github/workflows/update-connect-release.yml. The workflow verifies the GitHub release, Sigstore-signed channel manifest, tag commit, matching npm SDK, and release assets; regenerates src/data/connect-release.json and the Connect pin in site-sources.json; runs the complete website test suite; and opens a normal pull request. It never deploys or pushes main directly. The same workflow can be run manually with a tag to recover from a delayed npm publication or failed dispatch.

When Site checks passes on that pull request's exact head, .github/workflows/merge-connect-release.yml merges it, and the merge deploys through the normal main path. It acts only on a pull request opened by the release App on an automation/connect-release-v* branch, titled for that tag and changing only site-sources.json and src/data/connect-release.json. Any other pull request keeps its normal review and merge path.

The workflow uses a GitHub App configured as RELEASE_AUTOMATION_CLIENT_ID and RELEASE_AUTOMATION_APP_PRIVATE_KEY. Its installation on this repository needs only contents: write and pull requests: write. The App token ensures the resulting pull request triggers the ordinary protected Site checks workflow.

Development deployment

pnpm dlx wrangler@4.120.0 login # first use only
pnpm deploy:dev

The command builds the current working tree for https://mdbase-dev.pages.dev, imports the specification, builds the search index and Markdown copies, checks local links, and deploys the main branch of the standalone mdbase-dev Cloudflare Pages project. It verifies the live homepage, specification, canonical URLs, and indexing controls after deployment. The production GitHub Pages deployment and mdbase.dev domain are unchanged.

The command uses the existing mdbase-dev Cloudflare Pages project, whose production branch remains main. The sibling mdbase-spec/site/dist build is required, as it is for a local production build; MDBASE_SPEC_DIR and MDBASE_SPEC_SITE_DIST can point to another prepared checkout or artifact.