diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf7838d..6a04d50 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,82 +1,402 @@ # Contributing to inkform-docs -Thanks for helping out! This is a workspace monorepo for an open-source -documentation framework. +Thank you for helping improve inkform-docs! This guide covers everything you +need to get started — from running the monorepo locally to shipping a new +documentation theme that lands in the CLI's theme picker. -## Layout +## Table of contents +- [Prerequisites](#prerequisites) +- [Repository layout](#repository-layout) +- [Development workflow](#development-workflow) +- [CI and quality gates](#ci-and-quality-gates) +- [How the pieces fit](#how-the-pieces-fit) +- [Contributing a theme](#contributing-a-theme) +- [Contributing engine features](#contributing-engine-features) +- [Contributing to the CLI](#contributing-to-the-cli) +- [Pull request process](#pull-request-process) +- [Conventions](#conventions) +- [Source mirror (maintainers)](#source-mirror-maintainers) + +--- + +## Prerequisites + +- **Node.js 22+** — required by the framework and CI (see root `engines`) +- **npm** — this monorepo uses npm workspaces (not pnpm or Turborepo) +- A GitHub account with access to fork and open PRs against + [`inkform-dev/framework`](https://github.com/inkform-dev/framework) + +```bash +git clone https://github.com/inkform-dev/framework.git +cd framework +npm install ``` -packages/framework @inkform/framework — the MDX + OpenAPI engine -packages/cli @inkform/cli — the `npx` scaffolder -templates/* the themes (aurora, fern, cedar, mono, base, galley) -examples/* full demo sites (pokeapi-docs, markdown-docs, inkform-docs) + +--- + +## Repository layout + +``` +packages/ + framework/ @inkform/framework — the MDX + OpenAPI engine (published) + cli/ @inkform/cli — the npx scaffolder (published) + +templates/ + canopy/ @inkform/theme-canopy — dark, green accent (default) + shadcn/ @inkform/theme-shadcn — zinc monochrome + galley/ @inkform/theme-galley — warm paper + ink + +examples/ + pokeapi-docs/ Full PokéAPI docs site + Playwright e2e tests + markdown-docs/ Markdown/MDX feature reference + inkform-docs/ This framework's own documentation (dogfooded) + +archive/templates/ Legacy themes (aurora, fern, cedar, mono, base, galley) + preserved for reference — not scaffoldable via CLI ``` -## Develop +Only `@inkform/framework` and `@inkform/cli` are published to npm. Themes and +examples are private workspace packages used for development and demos. + +--- + +## Development workflow ```bash -npm install # installs every workspace +npm install # install every workspace + run postinstall prune npm run typecheck # typecheck all packages -npm test # framework's Vitest unit tests -npm run build # next build across every theme + example +npm test # framework unit tests (Vitest) +npm run build # next build across every theme + example +npm run build:examples # build the three demo sites only +``` -# run a theme or example: -npm run dev --workspace=@inkform/theme-aurora +**Run a workspace locally:** + +```bash +# Examples npm run dev --workspace=@inkform/example-pokeapi +npm run dev --workspace=@inkform/example-inkform-docs +npm run dev --workspace=@inkform/example-markdown + +# Themes +npm run dev --workspace=@inkform/theme-canopy +npm run dev --workspace=@inkform/theme-shadcn +npm run dev --workspace=@inkform/theme-galley +``` + +Changes to `packages/framework` are picked up immediately in themes and +examples via the workspace link and `transpilePackages` — no publish step +needed during development. + +**Scaffold from local templates** (essential when developing themes or the CLI): + +```bash +node packages/cli/bin/index.mjs init /tmp/test-docs --theme canopy --from templates -y +cd /tmp/test-docs && npm install && npm run dev +``` + +Override the GitHub ref the CLI downloads from with `INKFORM_DOCS_REF=` +when testing against a fork or feature branch. + +**End-to-end tests** (manual — deliberately excluded from CI): -# real-browser e2e smoke test (builds + serves pokeapi-docs, drives it with -# a real Chromium; the one test that makes a real request talks to the -# live PokeAPI once, not in a loop): +```bash npm run test:e2e --workspace=@inkform/example-pokeapi ``` -Each theme/example is a standalone Next.js 16 app; the framework resolves via the -workspace link, so changes to `packages/framework` are picked up immediately -(thanks to `transpilePackages`). +The e2e suite makes one real request to the live PokéAPI per run. Fine for a +developer running it locally once, but not wired into CI to avoid hammering a +free, community-funded API on every push. + +--- + +## CI and quality gates + +`.github/workflows/ci.yml` runs on every PR and push to `main`: + +``` +lint → typecheck → test → build → npm audit --audit-level=high +``` -`.github/workflows/ci.yml` runs `lint` → `typecheck` → `test` → `build` → -`npm audit --audit-level=high` on every PR (whatever branch it targets — some -in-flight work here stacks a chain of PRs branch-to-branch before eventually -landing on `main`) and on every push to `main`. Same commands as above; -nothing CI does that you can't run locally first. +Run the same commands locally before opening a PR. Nothing CI does that you +can't reproduce on your machine. + +> **Note:** No workspace has a `lint` script yet — CI runs it with +> `--if-present` so it's a no-op today and will activate automatically once +> one is added. + +--- ## How the pieces fit -- The **framework** is headless logic + a themeable component kit. The public API - contract is documented in +``` +┌─────────────────────────────────────────────────────────┐ +│ Content (MDX + docs.json + openapi.json) │ +└──────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────▼──────────────────────────────┐ +│ @inkform/framework — headless engine + component kit │ +│ (MDX, OpenAPI, search, MCP, AI, llms.txt) │ +└──────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────▼──────────────────────────────┐ +│ Theme — Next.js app that imports the kit + theme.css │ +└──────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────▼──────────────────────────────┐ +│ @inkform/cli — downloads a theme as a standalone app │ +└─────────────────────────────────────────────────────────┘ +``` + +- The **framework** is headless logic + a themeable component kit. The public + API contract lives in [`packages/framework/ARCHITECTURE.md`](./packages/framework/ARCHITECTURE.md). -- A **theme** is a full app that imports the kit and restyles it with a single - `app/theme.css` token file. Theme app code (routing, `lib/route.tsx`, the - `[[...slug]]` page, `components/`) is intentionally identical across themes — - the differences are tokens, fonts, and brand SVGs. -- The **CLI** downloads a theme as a standalone project. +- A **theme** is a full Next.js 16 app that imports the kit and restyles it + with a single `app/theme.css` token file. Routing, components, and page + structure are intentionally identical across themes — differences are tokens, + fonts, and brand SVGs. +- The **CLI** downloads a theme from GitHub (via giget) and scaffolds it as a + standalone project. + +--- + +## Contributing a theme + +New documentation site themes are one of the most valuable contributions you +can make. A well-designed theme that meets the contract below can be added to +the CLI's theme picker so every `npx @inkform/cli init` user can choose it. + +### What makes a good theme contribution + +- **Distinct visual identity** — it should look meaningfully different from + Canopy, Shadcn, and Galley. We want real variety, not a fourth green-accent + dark theme. +- **Polished defaults** — sample content, typography, spacing, and responsive + behavior should feel production-ready out of the box. +- **Token-driven styling** — all colors, radii, and density via `--fw-*` CSS + custom properties in `app/theme.css`. No hardcoded hex in components. +- **Accessible** — readable contrast, keyboard-navigable sidebar, sensible + focus states. Test light and dark modes if your theme supports both. +- **Complete contract** — ships every route and integration the contract + requires (see below). + +### The theme contract + +Every theme must satisfy the contract in +[`ARCHITECTURE.md` §12](./packages/framework/ARCHITECTURE.md#12-the-theme-contract). +In short, a theme is a standalone Next.js 16 app that: + +1. Has `content/docs/docs.json` + sample MDX + a sample `openapi.json`. +2. Imports `@inkform/framework/styles.css` once, then overrides `--fw-*` tokens + in `app/theme.css`. +3. Routes `/[[...slug]]` (docs), `/api-reference/[[...slug]]` (native OpenAPI + renderer), `/blog`, `/blog/[slug]`, and `/changelog`. +4. Builds a Pagefind search index via a `postbuild` script and mounts + ``, ``, and ``. +5. Ships `/api/ask` (AI ask-box, flag-gated), `/api/mcp` (MCP server), + `app/llms.txt` + `app/llms-full.txt`, `.env.example`, and a README with + content and deploy guides. +6. Sets `transpilePackages: ['@inkform/framework']` in `next.config.ts`. +7. Uses a unique workspace name `@inkform/theme-` and `"private": true`. + +**Themes differ by `theme.css` tokens, fonts, and brand assets — not by +re-implementing routing, the shell, or engine integrations.** + +### Step-by-step: adding a new theme + +1. **Copy an existing theme** as your starting point: + + ```bash + cp -r templates/canopy templates/ + ``` + + Canopy is the default and most complete reference. Use it unless you have a + specific reason to start from Shadcn or Galley. + +2. **Rename the package** in `templates//package.json`: -### Adding a theme + ```json + { + "name": "@inkform/theme-", + "description": " — one-line description" + } + ``` -1. Copy an existing theme dir (e.g. `templates/aurora`) to `templates/`. -2. Give it a unique `package.json` name (`@inkform/theme-`). -3. Restyle `app/theme.css` (tokens), `app/layout.tsx` (fonts), and `public/*.svg`. - Leave the routing/components alone. -4. Add it to the CLI's theme list in `packages/cli/src/scaffold.mjs`. -5. `npx tsc --noEmit` and `npx next build` must pass. +3. **Restyle** — this is where your design work lives: + - `app/theme.css` — override `--fw-*` design tokens (colors, radius, density) + - `app/layout.tsx` — font choices + - `public/logo.svg`, `public/favicon.svg`, `public/hero.svg` — brand assets + - `content/docs/docs.json` — update the sample site name and accent color -### Adding MDX components or engine features + Leave routing (`app/[[...slug]]/`, `lib/route.tsx`, `components/`) alone + unless you have a compelling UX reason and can justify the maintenance cost. -Implement in `packages/framework/src`, update `ARCHITECTURE.md`, and make sure -`npm run typecheck` passes from `packages/framework`. +4. **Verify locally:** + + ```bash + npm run typecheck --workspace=@inkform/theme- + npm run build --workspace=@inkform/theme- + npm run dev --workspace=@inkform/theme- + + # Scaffold test (from repo root): + node packages/cli/bin/index.mjs init /tmp/theme-test --theme --from templates -y + ``` + +5. **Register in the CLI** — add your theme to the `THEMES` array in + `packages/cli/src/scaffold.mjs`: + + ```js + { value: 'your-theme', label: 'Your Theme', hint: 'one-line description for the picker' }, + ``` + +6. **Write a theme README** at `templates//README.md` covering: + local dev, adding content, deploy to Vercel/Amplify, and any theme-specific + features (follow the Canopy README as a template). + +7. **Open a PR** with screenshots or a short screen recording showing your + theme in light and dark mode (if applicable), on desktop and mobile. + +### Theme review criteria + +Maintainers evaluate theme PRs on: + +| Criterion | What we look for | +| --- | --- | +| Visual quality | Distinct, polished, production-ready defaults | +| Contract compliance | All required routes, integrations, and build scripts present | +| Token hygiene | Styling via `--fw-*` tokens only; no hardcoded colors in components | +| Build health | `tsc --noEmit` and `next build` pass cleanly | +| Scaffold flow | `npx @inkform/cli init` with your theme produces a working project | +| Documentation | Theme README with content and deploy instructions | + +Themes that don't meet the bar can still be shared as community examples — we +just won't add them to the CLI picker until they're ready. + +--- + +## Contributing engine features + +Engine changes go in `packages/framework/src/`. + +1. Read [`ARCHITECTURE.md`](./packages/framework/ARCHITECTURE.md) first — + it is the stable API contract that themes, the CLI, and examples all build + against. +2. Implement in `packages/framework/src/`. +3. Add or update Vitest tests for non-trivial logic (`npm test`). +4. Update `ARCHITECTURE.md` if you change the public API (new exports, changed + behavior, new `docs.json` fields). +5. Verify downstream: `npm run typecheck` and `npm run build` from the repo root. + +If your change affects how themes wire up the engine (new route, new env var, +new component prop), update at least one theme as a reference implementation. + +--- + +## Contributing to the CLI + +The CLI lives in `packages/cli/`. Key files: + +| File | Purpose | +| --- | --- | +| `bin/index.mjs` | Entry point (`inkform-docs` binary) | +| `src/scaffold.mjs` | Scaffold logic, theme list, giget download | + +Test CLI changes locally: + +```bash +node packages/cli/bin/index.mjs init /tmp/cli-test --theme canopy --from templates -y +``` + +When adding a theme to the picker, only `scaffold.mjs` needs updating — the +CLI downloads templates from `github:inkform-dev/framework/templates/#main` +at scaffold time. + +--- + +## Pull request process + +1. **Fork** the repo and create a branch from `main`: + + ```bash + git checkout -b feat/my-contribution + ``` + +2. **Make your changes** following the conventions below. + +3. **Verify locally** before pushing: + + ```bash + npm run typecheck + npm test + npm run build + ``` + +4. **Open a PR** against `main` with: + - A clear title using [conventional commit](https://www.conventionalcommits.org/) style (`feat:`, `fix:`, `docs:`, `chore:`) + - A description of what changed and why + - Screenshots or recordings for visual changes (themes, UI components) + - A test plan — what you ran and what you verified + +5. **Address review feedback.** Maintainers may ask for changes before merging. + +### PR checklist + +- [ ] `npm run typecheck` passes +- [ ] `npm test` passes (if you touched `packages/framework`) +- [ ] `npm run build` passes +- [ ] `ARCHITECTURE.md` updated (if you changed the engine API) +- [ ] Theme README written (if you added a theme) +- [ ] CLI theme list updated (if you added a scaffoldable theme) +- [ ] No build artifacts committed (`.next/`, `*.tsbuildinfo`, `node_modules/`) + +--- + +## Conventions + +### Commits + +Use [conventional commit](https://www.conventionalcommits.org/) prefixes: + +``` +feat: add harbor theme with nautical tokens +fix: correct sidebar collapse on mobile +docs: update theme contract in ARCHITECTURE.md +chore: bump @inkform/framework to 0.4.1 +``` + +### TypeScript + +- Strict mode — no `any` that breaks the build +- ESM throughout (`"type": "module"` where applicable) + +### Styling + +- **Framework and theme components:** style only via `--fw-*` CSS custom + properties defined in `packages/framework/src/styles/tokens.css` and + overridden in each theme's `app/theme.css` +- **Icons:** [Lucide](https://lucide.dev/) with `strokeWidth={1.75}` (or + `~1.75`) +- **No hardcoded hex colors** in theme component files — use tokens + +### Files to never commit + +- `.next/`, `out/`, `.vercel/` +- `node_modules/` +- `*.tsbuildinfo` +- `.env.local` or any file containing secrets/API keys + +--- ## Source mirror (maintainers) This public repo is kept in sync with a private working monorepo via -`git subtree`. Merged PRs here are pulled back into the source, so contribute -normally — open a PR against this repo and it flows upstream. +`git subtree`. Merged PRs here are pulled back into the source repo, so +contribute normally — open a PR against this repo and it flows upstream. -## Conventions +--- -- Conventional-commit style messages (`feat:`, `fix:`, `docs:`, `chore:`). -- TypeScript strict; no `any` that breaks the build. -- Style only via `--fw-*` tokens + Lucide icons (`strokeWidth` ~1.75); no - hardcoded hex in theme components. -- Don't commit build artifacts (`.next`, `*.tsbuildinfo`) — they're gitignored. +## License -By contributing you agree your work is licensed under the repository's MIT license. +By contributing, you agree that your contributions are licensed under the +repository's [MIT License](./LICENSE). diff --git a/README.md b/README.md index 45db464..b8f7d2d 100644 --- a/README.md +++ b/README.md @@ -2,87 +2,174 @@ # inkform-docs -**Open-source documentation framework for Next.js.** Beautiful docs, API -reference from OpenAPI, blog, and changelog — from a folder of Markdown. +**Open-source documentation framework for Next.js.** -`npx @inkform/cli@latest init my-docs` +Beautiful docs, native API reference from OpenAPI, blog, and changelog — from a folder of Markdown. + +
+ +[![CI](https://github.com/inkform-dev/framework/actions/workflows/ci.yml/badge.svg)](https://github.com/inkform-dev/framework/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) +[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](./package.json) + +```bash +npx @inkform/cli@latest init my-docs +``` + +[Get started](#get-started) · [Themes](#themes) · [Features](#features) · [Develop](#develop-in-this-repo) · [Contributing](./CONTRIBUTING.md) --- -This is a monorepo. It contains: +## What is inkform-docs? -| Package | What it is | -| --- | --- | -| [`packages/framework`](./packages/framework) | `@inkform/framework` — the MDX + OpenAPI rendering engine | -| [`packages/cli`](./packages/cli) | `@inkform/cli` — `npx` scaffolder (pick a theme, get a project) | -| [`templates/aurora`](./templates/aurora) | classic dark docs theme | -| [`templates/fern`](./templates/fern) | clean, friendly green theme with Guides / API tabs | -| [`templates/cedar`](./templates/cedar) | warm, editorial theme | -| [`templates/mono`](./templates/mono) | monospace / brutalist theme | -| [`templates/base`](./templates/base) | minimal, unopinionated starter | -| [`templates/galley`](./templates/galley) | Inkform's own design system — warm paper + ink, one editorial red accent | -| [`examples/pokeapi-docs`](./examples/pokeapi-docs) | a full docs site for the PokéAPI | -| [`examples/markdown-docs`](./examples/markdown-docs) | a full docs site about Markdown | -| [`examples/inkform-docs`](./examples/inkform-docs) | the framework's own docs — dogfooded with the Galley theme | - -## Why inkform-docs - -- **Markdown in, polished docs out.** Write MDX, commit it, deploy. No CMS, no - database, no build service — your repo is the source of truth. -- **API reference is OpenAPI-first — and framework-native.** Point `docs.json` - at an OpenAPI spec and you get a searchable, paginated, "Try it"-enabled API - reference automatically. Rendered with the framework's own React - components — **zero Scalar/Vue dependency**, real per-operation pages - (SSG'd, not a client-side SPA embed), a real Try It console that makes - actual requests. Everything else is MDX. -- **Your docs are an MCP server.** Ship `/api/mcp` and every page — guides and - API operations alike — becomes callable by Claude, Cursor, or any MCP - client: `search`, `get_operation`, `list_operations`, `get_doc`. Self-hosted, - no external platform, no billing — it's just another Next.js route handler. -- **An AI ask-box grounded in your actual content**, not a hosted black box. - BYO model (Anthropic, OpenAI, or Google) and BYO API key; retrieval reuses - the same search the MCP server exposes, so the answers and the sources it - cites both trace back to real pages. -- **`/llms.txt` and `/llms-full.txt` out of the box** — the emerging - convention ([llmstxt.org](https://llmstxt.org)) for giving LLMs a plain-text - entry point into your content without crawling HTML. -- **Themes you actually choose between.** Five production themes that look - nothing alike, plus a minimal base — all driven by the same engine, so you can - switch with a token file. -- **Own your deployment.** It's a normal Next.js app. Ship it to Vercel, AWS - Amplify, a container, or under a path on a site you already run. -- **Genuinely open.** MIT, no telemetry, no required account, no lock-in. +**inkform-docs** is a self-hosted documentation framework. You write MDX, configure navigation in a single `docs.json` file, and deploy a normal Next.js app. No CMS, no database, no vendor lock-in. + +The engine (`@inkform/framework`) handles rendering, search, OpenAPI parsing, and optional AI/MCP integrations. Themes are thin Next.js apps that restyle the engine with CSS tokens. The CLI scaffolds a ready-to-deploy project in one command. + +``` +┌─────────────────────────────────────────────────────────┐ +│ Your content (MDX + docs.json + openapi.json) │ +└──────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────▼──────────────────────────────┐ +│ @inkform/framework — MDX, OpenAPI, search, MCP, AI │ +└──────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────▼──────────────────────────────┐ +│ Theme (Canopy / Shadcn / Galley) — tokens + layout │ +└──────────────────────────┬──────────────────────────────┘ + │ + Next.js 16 app → deploy anywhere +``` ## Get started +**Prerequisites:** [Node.js 22+](https://nodejs.org/) and npm. + ```bash npx @inkform/cli@latest init my-docs cd my-docs npm install -npm run dev +npm run dev # → http://localhost:3000 +``` + +The CLI prompts for a project folder and a theme, then writes a standalone Next.js project. Edit `content/docs/` to add pages, update `content/docs/docs.json` for navigation, and run `npm run build` when you're ready to deploy. + +**CLI options:** + +```bash +npx @inkform/cli@latest init my-docs --theme galley # skip theme prompt +npx @inkform/cli@latest init my-docs --openapi ./spec.yaml # wire up API reference +npx @inkform/cli@latest init my-docs -y # accept defaults ``` -The CLI asks for a project folder and a theme, then writes a standalone Next.js -project with a README that walks you through adding content and deploying. +The binary is also available as `inkform-docs` when installed globally. + +To embed the engine in an existing Next.js app or build a custom theme from scratch, see [`packages/framework`](./packages/framework) and [`packages/framework/ARCHITECTURE.md`](./packages/framework/ARCHITECTURE.md). + +## Features + +| | | +| --- | --- | +| **Markdown in, polished docs out** | Write MDX, commit it, deploy. Your repo is the source of truth — no CMS or build service required. | +| **Native OpenAPI API reference** | Point `docs.json` at a spec and get searchable, paginated, per-operation pages with a real Try It console. Rendered with the framework's own React components — zero Scalar/Vue dependency. | +| **MCP server** | Ship `/api/mcp` and every page becomes callable by Claude, Cursor, or any MCP client: `search`, `get_doc`, `list_operations`, `get_operation`. Self-hosted, no billing. | +| **AI ask-box** | BYO model (Anthropic, OpenAI, or Google) and API key. Answers are grounded in your actual content with cited sources. | +| **`/llms.txt` out of the box** | The [llms.txt](https://llmstxt.org) convention — a curated index and full-corpus export for LLMs and agentic tools. | +| **Full-text search** | [Pagefind](https://pagefind.app/) indexes your built HTML at deploy time. Fast, client-side, no server required. | +| **Blog & changelog** | Drop files in `content/blog/` or `content/changelog/` — routes and nav links appear automatically. | +| **Own your deployment** | A normal Next.js app. Ship to Vercel, AWS Amplify, a container, or a subpath on an existing site. | +| **Genuinely open** | MIT licensed. No telemetry, no required account, no lock-in. | + +## Themes + +Three production themes share one proven app structure. They differ only in design tokens, fonts, and brand assets — so switching themes is mostly a CSS file change. -To build your own theme or embed the engine in an existing app, see -[`packages/framework`](./packages/framework). +| Theme | Style | Best for | +| --- | --- | --- | +| [**Canopy**](./templates/canopy) *(default)* | Dark, vivid green accent, collapsible sidebar | Developer docs, API-first products | +| [**Shadcn**](./templates/shadcn) | Zinc monochrome, shadcn/ui aesthetic | Teams already on the shadcn design language | +| [**Galley**](./templates/galley) | Warm paper + ink, editorial red accent | Inkform's own design system — editorial, brand-forward sites | + +Legacy themes (Aurora, Fern, Cedar, Mono, Base, and an older Galley) are preserved in [`archive/templates/`](./archive/templates/) for reference but are not scaffoldable via the CLI. + +**Want to contribute a new theme?** See [Contributing a theme](./CONTRIBUTING.md#contributing-a-theme) — great designs can be added to the CLI's theme picker. + +## Monorepo + +This repository is an npm workspaces monorepo. Published packages ship to npm; everything else is private and used for development and demos. + +| Path | Package | Published | What it is | +| --- | --- | :---: | --- | +| [`packages/framework`](./packages/framework) | `@inkform/framework` | ✓ | The MDX + OpenAPI rendering engine | +| [`packages/cli`](./packages/cli) | `@inkform/cli` | ✓ | `npx` scaffolder (`inkform-docs` binary) | +| [`templates/canopy`](./templates/canopy) | `@inkform/theme-canopy` | | Canopy theme | +| [`templates/shadcn`](./templates/shadcn) | `@inkform/theme-shadcn` | | Shadcn theme | +| [`templates/galley`](./templates/galley) | `@inkform/theme-galley` | | Galley theme | +| [`examples/pokeapi-docs`](./examples/pokeapi-docs) | `@inkform/example-pokeapi` | | Full PokéAPI docs site (OpenAPI + e2e tests) | +| [`examples/markdown-docs`](./examples/markdown-docs) | `@inkform/example-markdown` | | Markdown/MDX feature reference | +| [`examples/inkform-docs`](./examples/inkform-docs) | `@inkform/example-inkform-docs` | | This framework's own docs (dogfooded) | ## Develop in this repo +**Prerequisites:** Node.js 22+, npm. + ```bash -npm install # installs all workspaces -npm run typecheck # typecheck every package -npm run dev --workspace=@inkform/example-pokeapi # run an example +git clone https://github.com/inkform-dev/framework.git +cd framework +npm install # installs all workspaces +npm run typecheck # typecheck every package +npm test # framework unit tests (Vitest) +npm run build # build all workspaces +npm run build:examples # build the three demo sites only ``` +**Run a workspace locally:** + +```bash +# Examples +npm run dev --workspace=@inkform/example-pokeapi +npm run dev --workspace=@inkform/example-inkform-docs +npm run dev --workspace=@inkform/example-markdown + +# Themes +npm run dev --workspace=@inkform/theme-canopy +npm run dev --workspace=@inkform/theme-shadcn +npm run dev --workspace=@inkform/theme-galley +``` + +**Scaffold from local templates** (useful when developing themes or the CLI): + +```bash +node packages/cli/bin/index.mjs init /tmp/test-docs --theme canopy --from templates -y +``` + +**End-to-end tests** (manual — not in CI, to avoid hammering the live PokéAPI): + +```bash +npm run test:e2e --workspace=@inkform/example-pokeapi +``` + +Changes to `packages/framework` are picked up immediately in themes and examples via the workspace link and `transpilePackages`. + +See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full contributor guide — PR process, theme requirements, and conventions. + +## Documentation + +| Doc | Description | +| --- | --- | +| [ARCHITECTURE.md](./packages/framework/ARCHITECTURE.md) | Engine API contract — read this before writing a theme or extending the framework | +| [CONTRIBUTING.md](./CONTRIBUTING.md) | How to contribute code, themes, and fixes | +| [CHANGELOG.md](./CHANGELOG.md) | Release history | +| [MIGRATION.md](./MIGRATION.md) | Upgrade guide (e.g. 0.3 → 0.4 native API renderer) | +| [PUBLISHING.md](./packages/framework/PUBLISHING.md) | Maintainer release process for npm packages | + ## Changelog -See [`CHANGELOG.md`](./CHANGELOG.md). Upgrading from an existing `docs.json` -and want to know what changed? See [`MIGRATION.md`](./MIGRATION.md). +See [`CHANGELOG.md`](./CHANGELOG.md). Upgrading from an existing `docs.json`? See [`MIGRATION.md`](./MIGRATION.md). ## License -MIT. +[MIT](./LICENSE) — Copyright (c) 2026 inkform.