@waveso/docs 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,334 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { Root } from "hast";
+//#region src/types.d.ts
+/**
+ * The frontmatter fields the package itself understands.
+ *
+ * Consumers extend this with their own schema — {@link DocsConfig.frontmatterSchema} —
+ * and the extra fields flow through the generic parameter on {@link DocFile}
+ * and friends rather than widening this interface.
+ */
+interface DocFrontmatter {
+  /** Page title. Used for `<h1>` fallbacks, `<title>`, and search. */
+  title: string;
+  /** One-line summary. Used for `<meta name="description">` and search. */
+  description?: string;
+  /**
+   * Sidebar label, when it should differ from {@link DocFrontmatter.title}.
+   * Sidebars are narrow; page ancestors are not.
+   */
+  label?: string;
+  /**
+   * Excluded from navigation, search and `generateStaticParams`.
+   *
+   * Deliberately not tied to `NODE_ENV`: Vercel preview deployments are
+   * production builds, so branching on it would hide drafts in exactly the
+   * place reviewers look. Gate on an explicit config flag instead.
+   */
+  draft?: boolean;
+  /**
+   * Previous URLs for this page, relative to the docs base path
+   * (e.g. `['old-name', 'legacy/old-name']`). The Next adapter turns these
+   * into permanent redirects so a rename never becomes a silent 404.
+   */
+  aliases?: string[];
+  /**
+   * Sort weight within its directory, for directories without a `meta.json`.
+   * Lower sorts first; pages without an order sort last, alphabetically.
+   */
+  order?: number;
+}
+/**
+ * A single documentation page discovered on disk.
+ *
+ * `segments` is the canonical identity; `slug` and `href` are derived and
+ * cached for convenience. An `index.md` at the content root has an empty
+ * `segments` array and maps to the base path itself.
+ */
+interface DocFile<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
+  /** Route segments, e.g. `['api', 'auth']`. Empty for the root index page. */
+  segments: string[];
+  /** `segments.join('/')`, e.g. `'api/auth'`. Empty string for the index. */
+  slug: string;
+  /** Fully-qualified route, e.g. `'/docs/api/auth'`. */
+  href: string;
+  /** Absolute path on disk. */
+  filePath: string;
+  /** Path relative to the content root, e.g. `'api/auth.md'`. */
+  relativePath: string;
+  /** Validated frontmatter. */
+  frontmatter: TFrontmatter;
+  /** Markdown body with the frontmatter block removed. */
+  content: string;
+}
+/** A link to a documentation page. */
+interface DocNavPage {
+  type: 'page';
+  title: string;
+  href: string;
+  slug: string;
+}
+/**
+ * A directory. `href` is present when the directory has an `index.md`, in
+ * which case the group heading is itself a link.
+ */
+interface DocNavGroup {
+  type: 'group';
+  title: string;
+  href?: string;
+  children: DocNavNode[];
+}
+/** A non-interactive heading between groups, from `"---Label---"` in meta.json. */
+interface DocNavSeparator {
+  type: 'separator';
+  title: string;
+}
+/** An arbitrary external link, from an object entry in meta.json. */
+interface DocNavLink {
+  type: 'link';
+  title: string;
+  href: string;
+  external: boolean;
+}
+type DocNavNode = DocNavPage | DocNavGroup | DocNavSeparator | DocNavLink;
+/**
+ * Per-directory ordering and labelling, read from `meta.json`.
+ *
+ * Chosen over numeric filename prefixes because a filename cannot express
+ * separators, external links, or a directory title — all of which a real
+ * docs sidebar needs — and because `01_mental_model.md` violates kebab-case
+ * twice over.
+ *
+ * `pages` accepts:
+ *  - `"getting-started"` — a file or subdirectory in this directory
+ *  - `"---Reference---"` — a separator with the enclosed label
+ *  - `"..."`             — everything not named explicitly, alphabetically
+ *  - `"...api"`          — expand the `api` subdirectory inline
+ *  - `{ title, href }`   — an arbitrary link
+ */
+interface DocsMeta {
+  /** Directory title, shown as the group heading. Defaults to the dirname. */
+  title?: string;
+  /** Ordered entries. Omit to sort by frontmatter `order`, then alphabetically. */
+  pages?: Array<string | {
+    title: string;
+    href: string;
+  }>;
+}
+/**
+ * A heading captured from the rendered tree.
+ *
+ * These ids come from the same `rehype-slug` pass that annotated the document,
+ * so anchors match by construction rather than by a second parse with a
+ * separately-seeded slugger — which drifts precisely where it hurts, on
+ * duplicate headings that get `-1` collision suffixes.
+ */
+interface TocEntry {
+  id: string;
+  text: string;
+  /** Heading level, 2–6. `h1` is the page title and is never in the TOC. */
+  depth: number;
+  children: TocEntry[];
+}
+/**
+ * A parsed, highlighted document, ready to be turned into React elements.
+ *
+ * `hast` is a plain serialisable tree — it survives the RSC boundary, a
+ * `JSON.stringify` round-trip through any build-time artifact — a cache file,
+ * a bundler virtual module — equally well. Rendering it is the consumer's
+ * business.
+ */
+interface RenderedDoc<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
+  frontmatter: TFrontmatter;
+  hast: Root;
+  toc: TocEntry[];
+  /** Route segments of the document this was rendered from. */
+  segments: string[];
+  href: string;
+}
+/**
+ * One indexable unit: a heading and the prose beneath it.
+ *
+ * Section-scoped rather than page-scoped so a hit can deep-link to the right
+ * heading instead of dropping the reader at the top of a 2,000-word page.
+ * The byte saving over full-page records is real but modest (~1.4x) — the
+ * deep link is the point.
+ */
+interface SearchRecord {
+  /**
+   * Stable id: `slug#anchor`, or the bare slug for a page's lead section.
+   *
+   * ⚠️ NOT THE `href`, WHICH IS WHAT IT USED TO BE. Two reasons, and both are
+   * about the shipped `search-index.json` rather than about tidiness. It
+   * carried the whole route twice per record, on the one artifact the README
+   * sells on download size. And an href embeds `basePath`, so a site moving
+   * from `/docs` to `/reference` changed the identity of every record for no
+   * reason. A slug survives that.
+   */
+  id: string;
+  /** Page title. */
+  title: string;
+  /** Heading text for this section; equals `title` for the lead section. */
+  heading: string;
+  /**
+   * Ancestor headings, outermost first.
+   *
+   * NAMED FOR WHAT IT IS, not for what the dialog does with it. This was
+   * `titles`, which sat between `title` and `heading` and meant neither — three
+   * fields whose names differed by a plural. The UI turning these into
+   * breadcrumbs is the UI's decision; the record is data.
+   */
+  ancestors: string[];
+  /** Route including the anchor, e.g. `/docs/api/auth#bearer-token`. */
+  href: string;
+  /** Plain text of the section, truncated to the configured excerpt length. */
+  text: string;
+}
+/**
+ * Where a link or an image was authored: the route AND the directory.
+ *
+ * ⚠️ BOTH, AND THE DIFFERENCE IS THE ENTIRE REASON THIS IS AN OBJECT. `api.md`
+ * and `api/index.md` produce IDENTICAL route segments — `['api']` — and resolve
+ * `./auth.md` to different pages, because one folds against the content root
+ * and the other against `api/`. Only the on-disk path separates them.
+ *
+ * The resolvers used to receive route segments alone, so a custom resolver was
+ * handed strictly less than the built-in one had and could not get
+ * `./sibling.md` right on any directory index page. No rule recovers the
+ * directory from the route, which is why the fix had to be the argument rather
+ * than a note in the docs.
+ */
+interface DocLinkContext {
+  /** Route segments of the containing document, e.g. `['api', 'auth']`. */
+  segments: string[];
+  /**
+   * Directory segments of the SOURCE FILE, relative to the content root:
+   * `['api']` for both `api/auth.md` and `api/auth/index.md`. This is what a
+   * relative href folds against.
+   */
+  dirSegments: string[];
+  /** The source path, e.g. `'api/auth.md'`. For error messages. */
+  relativePath: string;
+}
+/**
+ * Resolve an internal markdown link target to a route.
+ *
+ * Called for every relative link found in the source. Returning `undefined`
+ * signals "not a documentation page", which — with `assertLinks` on — fails
+ * the build rather than shipping a 404 that was valid on GitHub.
+ */
+type LinkResolver = (
+/** The raw href as authored, e.g. `'./api/auth.md'`. */
+href: string, from: DocLinkContext) => string | undefined;
+/**
+ * Resolve an image `src` to a public URL and its intrinsic dimensions.
+ *
+ * Dimensions are read at build time because markdown carries none and
+ * `next/image` refuses to render without them (short of `fill`).
+ *
+ * ⚠️ `src` ARRIVES FOLDED AND CONTAINED. A `../` chain is resolved against
+ * `from.dirSegments` before this is called, and one that climbs above the
+ * content root throws instead of reaching you — so an implementation that joins
+ * this onto a filesystem path is not handing a document author a way to read
+ * `../../../../.env`. That was not true before: images skipped folding
+ * entirely and arrived exactly as authored.
+ *
+ * Two shapes are the exception, and they still reach you: an absolute
+ * `/logo.png` and a schemed `https://…` are passed through UNFOLDED, because the
+ * first is already a public URL and the second belongs to someone else. Folding
+ * them would be meaningless, but they are not filtered out — a host that wants
+ * to rewrite `/logo.png` onto a CDN needs the call. So an implementation that
+ * blindly prefixes what it is handed produces `/cdn//logo.png` and
+ * `/cdn/https://example.com/a.png`. Branch on them, or return `undefined` to
+ * leave the src as authored.
+ */
+type ImageResolver = (src: string, from: DocLinkContext) => Promise<{
+  src: string;
+  width?: number;
+  height?: number;
+} | undefined> | {
+  src: string;
+  width?: number;
+  height?: number;
+} | undefined;
+/**
+ * How a documentation tree is read.
+ *
+ * The type parameter is inferred from
+ * {@link DocsConfig.frontmatterSchema} — pass one and every `DocFile` and
+ * `RenderedDoc` the host hands back carries your fields, with no explicit type
+ * argument anywhere. Omit it and the parameter defaults to
+ * {@link DocFrontmatter}, which is what every existing call site gets.
+ */
+interface DocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
+  /**
+   * Content root. Relative paths resolve against `process.cwd()`, which is
+   * the project root during both `next build` and `vite build`.
+   */
+  contentDir: string;
+  /** URL prefix the docs are mounted at. Defaults to `'/docs'`. */
+  basePath?: string;
+  /**
+   * Include pages marked `draft: true`. Defaults to `false`.
+   *
+   * Drive this from your own env check — deliberately not `NODE_ENV`.
+   */
+  includeDrafts?: boolean;
+  /**
+   * Fail the build when an internal link resolves to a page that does not
+   * exist. Defaults to `true`; there is no good reason to turn it off.
+   */
+  assertLinks?: boolean;
+  /**
+   * Validates every page's frontmatter. Defaults to `docFrontmatterSchema`
+   * from `@waveso/docs/frontmatter`.
+   *
+   * Any [Standard Schema](https://standardschema.dev) validator is accepted —
+   * Zod, Valibot, ArkType — rather than a Zod type specifically. That keeps the
+   * package from dictating a validator, and a schema handed over through the
+   * spec interface cannot hit the cross-instance mismatch two copies of Zod in
+   * one `node_modules` otherwise produce.
+   *
+   * ```ts
+   * // content/docs-schema.ts — one module, imported by every route file
+   * import { docFrontmatterSchema } from '@waveso/docs/frontmatter';
+   * import { z } from 'zod';
+   *
+   * export const frontmatterSchema = docFrontmatterSchema.extend({
+   *   audience: z.enum(['user', 'operator']).exactOptional(),
+   * });
+   * ```
+   *
+   * Three things are worth knowing before you write one:
+   *
+   *  - **The output must still satisfy {@link DocFrontmatter}.** `title` drives
+   *    the `<h1>` fallback and `<title>`, `draft` the visibility filter,
+   *    `aliases` the redirects, `order`/`label` the sidebar. A schema that
+   *    drops them is a compile error here, not a mystery at render time.
+   *  - **Unknown keys are stripped, by every validator worth using.** The
+   *    parsed frontmatter is exactly what the schema declares, so declare every
+   *    field you intend to read — extending
+   *    `docFrontmatterSchema` is the shortest way to keep the built-ins.
+   *  - **Identity is load-bearing.** The filesystem scan is memoised per
+   *    resolved config, and two schema objects are only "the same schema" when
+   *    they are the same object. Export one from a shared module (as above)
+   *    rather than building it inline in each route file, or each file pays for
+   *    its own scan.
+   */
+  frontmatterSchema?: StandardSchemaV1<unknown, TFrontmatter>;
+}
+/** {@link DocsConfig} with defaults applied. */
+interface ResolvedDocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
+  contentDir: string;
+  basePath: string;
+  includeDrafts: boolean;
+  assertLinks: boolean;
+  /**
+   * As supplied. Absent — never explicitly `undefined`, per
+   * `exactOptionalPropertyTypes` — when the built-in `docFrontmatterSchema`
+   * applies, so the default lives in one place: `parseFrontmatter`.
+   */
+  frontmatterSchema?: StandardSchemaV1<unknown, TFrontmatter>;
+}
+//#endregion
+export { DocFile, DocFrontmatter, DocLinkContext, DocNavGroup, DocNavLink, DocNavNode, DocNavPage, DocNavSeparator, DocsConfig, DocsMeta, ImageResolver, LinkResolver, RenderedDoc, ResolvedDocsConfig, SearchRecord, TocEntry };

package/package.json

@@ -0,0 +1,166 @@
+{
+  "name": "@waveso/docs",
+  "version": "0.1.0",
+  "description": "Markdown documentation for Next.js — parsed to hast in Node at build time, rendered as your own React components, zero parser bytes in the browser",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "documentation",
+    "docs",
+    "markdown",
+    "remark",
+    "rehype",
+    "shiki",
+    "nextjs",
+    "react-server-components",
+    "static-site"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wavedotso/wave-docs.git"
+  },
+  "homepage": "https://github.com/wavedotso/wave-docs#readme",
+  "bugs": "https://github.com/wavedotso/wave-docs/issues",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    "./styles.css": "./dist/styles.css",
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./frontmatter": {
+      "types": "./dist/frontmatter.d.ts",
+      "default": "./dist/frontmatter.js"
+    },
+    "./source": {
+      "types": "./dist/source.d.ts",
+      "browser": null,
+      "default": "./dist/source.js"
+    },
+    "./render": {
+      "types": "./dist/render.d.ts",
+      "browser": null,
+      "default": "./dist/render.js"
+    },
+    "./highlighter": {
+      "types": "./dist/highlighter.d.ts",
+      "browser": null,
+      "default": "./dist/highlighter.js"
+    },
+    "./search-index": {
+      "types": "./dist/search-index.d.ts",
+      "browser": null,
+      "default": "./dist/search-index.js"
+    },
+    "./search-options": {
+      "types": "./dist/search-options.d.ts",
+      "default": "./dist/search-options.js"
+    },
+    "./markdown-links": {
+      "types": "./dist/plugins/remark-doc-links.d.ts",
+      "default": "./dist/plugins/remark-doc-links.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "browser": null,
+      "default": "./dist/next.js"
+    },
+    "./react/*": {
+      "types": "./dist/react/*.d.ts",
+      "default": "./dist/react/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@shikijs/langs": "4.4.3",
+    "@shikijs/rehype": "4.4.3",
+    "@shikijs/themes": "4.4.3",
+    "@standard-schema/spec": "^1.1.0",
+    "@types/hast": "^3.0.5",
+    "@types/mdast": "^4.0.4",
+    "gray-matter": "^4.0.3",
+    "hast-util-to-jsx-runtime": "^2.3.6",
+    "hast-util-to-string": "^3.0.1",
+    "minisearch": "^7.2.0",
+    "rehype-autolink-headings": "^7.1.0",
+    "rehype-github-alerts": "^4.2.0",
+    "rehype-slug": "^6.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "shiki": "4.4.3",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0",
+    "vfile": "^6.0.3"
+  },
+  "peerDependencies": {
+    "next": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^4.0.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "tailwindcss": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@biomejs/biome": "^2.5.7",
+    "@changesets/cli": "^2.31.1",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.3",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "image-size": "^2.0.2",
+    "jsdom": "^30.0.1",
+    "next": "^16.3.0",
+    "publint": "^0.3.23",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.3",
+    "unrun": "^0.3.1",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=22.18.0",
+      "onFail": "warn"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check:package": "publint && attw --pack . --ignore-rules no-resolution cjs-resolves-to-esm",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "pnpm run build && changeset publish"
+  }
+}