Fedify docs

This directory contains the source files of the Fedify docs. The docs are written in Markdown format and are built with VitePress.

To build the docs locally, start the development server from the repository root (mise provisions the required tools and dependencies for you):

mise run docs

Once the development server is running, you can open your browser and navigate to http://localhost:5173/ to view the docs.

Team page data

The maintainer profiles in .vitepress/team.mts are maintained by hand. The contribution years record each person's first contribution, rather than their appointment as a maintainer. The profile images under public/team/ come from Hong Minhee's website and the DrFed website source.

The team.data.ts loader fetches all pages of GitHub contributors at build time. Set GITHUB_TOKEN in the build environment to authenticate these requests; the token stays in the build process and is never sent to the browser. If GitHub is unavailable, the loader uses .vitepress/data/contributors.json. Refresh that fallback snapshot with the id, login, and type fields from every page of the repository's contributors API when needed.

After hydration, the team page refreshes the list without authentication and caches successful results in browser storage for one hour. Failed requests leave the existing list visible. Both paths use the filtering in .vitepress/contributors.mts, which excludes maintainers, bot accounts, and explicitly listed AI agent account IDs. Add agent IDs there rather than matching names that might belong to people.

Run mise run test:docs-contributors to check pagination, filtering, and failure handling.

VitePress documentation conventions

The docs/ directory uses VitePress with additional features beyond standard Markdown.

Twoslash code blocks

Use the twoslash modifier to enable TypeScript type checking and hover information in code blocks:

~~~~ typescript twoslash
import { createFederation } from "@fedify/fedify";

const federation = createFederation({ kv: undefined! });
~~~~

Fixture variables

When code examples need variables that shouldn't be shown to readers, declare them before the // ---cut-before--- directive. Content before this directive is compiled but hidden from display:

~~~~ typescript twoslash
import type { KvStore } from "@fedify/fedify";
declare const kv: KvStore;
// ---cut-before---
import { createFederation } from "@fedify/fedify";

const federation = createFederation({ kv });
~~~~

The reader sees only the code after ---cut-before---, but TypeScript checks the entire block including the hidden fixture.

Code groups

Use code groups to show the same content for different package managers or environments. When showing equivalent runtimes or package managers, list Node.js and its package managers first.

::: code-group

~~~~ bash [npm]
npm add @fedify/fedify
~~~~

~~~~ bash [pnpm]
pnpm add @fedify/fedify
~~~~

~~~~ bash [Deno]
deno add jsr:@fedify/fedify
~~~~

:::

Internal links

• When linking to other VitePress documents within the docs/ directory, use inline link syntax (e.g., [text](./path/to/file.md)) instead of reference-style links.
• Always use relative paths for internal links.
• Include the .md extension in internal link paths.

Definition lists

Prefer definition lists over bulleted lists for term-definition pairs. Descriptions should be written as full sentences (sentence case, ending with a period). List multiple terms for one description on separate lines:

Term 1
Term 2
:   Description starts with a capital letter and ends with a period.

Building documentation

mise run docs:build    # Build for production (runs Twoslash type checking)
mise run docs          # Start development server

Always run mise run docs:build before committing to catch Twoslash type errors.