Pact API Docs

Next.js documentation site for the Pact API, built with Markdown and shadcn/ui.

Development

npm install
npm run generate:ai
npm run dev

Open http://localhost:3000/.

Content

Docs are Markdown files under two locale trees:

Locale	Source	Site URL
Russian (default)	content/ru/	/…
English	content/en/	/en/…

The language switcher in the top bar maps the same path between locales (for example /v2/messages ↔ /en/v2/messages).

Keep both locales in sync. Every page should exist in content/ru/ and content/en/ with the same relative path and the same frontmatter title / description translated.

File → URL

Path under content/{locale}/ maps to the URL (Russian unprefixed, English under /en):

File	RU URL	EN URL
content/ru/index.md	/	—
content/en/index.md	—	/en/
content/ru/v2/messages/send-message.md	/v2/messages/send-message/	/en/v2/messages/send-message/
content/ru/embed/overview.md	/embed/overview/	/en/embed/overview/

Use a folder + index.md only when you need a section index at that folder path (for example content/ru/v2/messages/index.md → /v2/messages/).

Frontmatter

---
title: "Send a message"
description: "Send a message to an existing conversation"
section: "v2"
---

• title — page H1 and sidebar / prev-next label source when used with nav
• description — subtitle under the H1
• section — optional grouping hint (for example v2, embed)

Edit an existing page

1. Change the Markdown in both content/ru/… and content/en/….
2. Use locale-neutral internal links: [Send message](/v2/messages/send-message) — the site prefixes /en automatically for English.
3. Run npm run generate:ai (also runs on npm run build) so public/docs/** and public/llms.txt stay in sync.
4. Check the page in the browser for RU and EN.

Add a new page

1. Create matching files, for example:
   • content/ru/v2/messages/my-endpoint.md
   • content/en/v2/messages/my-endpoint.md
2. Fill frontmatter and body in both languages.
3. Register the page in the sidebar in lib/nav.ts (see below).
4. Run npm run generate:ai and open /v2/messages/my-endpoint/ and /en/v2/messages/my-endpoint/.

Add or change a sidebar section

Navigation is defined once in lib/nav.ts as navSectionDefs. Each section and item has ru / en titles and a shared unprefixed href:

{
  title: { ru: "Сообщения", en: "Messages" },
  href: "/v2/messages",
  items: [
    {
      title: { ru: "Отправить сообщение", en: "Send a message" },
      href: "/v2/messages/send-message",
    },
  ],
},

• Top-level title on a section is the sidebar group label.
• Nested items become expandable children.
• Optional flags: deprecated: true, external: true (non-doc link such as /llms.txt). HTTP method badges are filled automatically from a page’s ## HTTP Request block when present.
• After changing nav or content, restart or refresh npm run dev if the sidebar looks stale.

Markdown extras

• Callouts: > **Note:** …, > **Warning:** …, > **Success:** … (Russian labels Заметка / Внимание / Готово also work).
• Code tabs: consecutive fenced blocks in tabbable languages (for example shell + php, or js / python / php / ruby) are merged into a tabbed code block.
• HTTP Request: a single ## HTTP Request section with `METHOD url` is lifted into the page header badge.
• Anchors: optional {#custom-id} on headings for stable fragment links across locales.

AI-ready

• Copy page / View as Markdown on every docs page
• Raw Markdown mirrored under /docs/**/*.md (RU) and /docs/en/**/*.md (EN)
• Catalog at /llms.txt (generated by npm run generate:ai / build)

Deploy (GitHub Pages)

Push to gh-pages. The workflow sets:

NEXT_PUBLIC_BASE_PATH=/${{ github.event.repository.name }}

That publishes to https://pact-im.github.io/api-doc/. After the first Actions deploy, set Pages source to GitHub Actions.