Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions .github/workflows/pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,6 @@ jobs:
version: 2026.11.8
install_args: --locked
- run: pnpm install --frozen-lockfile
# Mermaid diagrams are rendered at build time in headless Chromium.
- run: pnpm exec playwright install --with-deps chromium
- run: mise run build
- if: github.event_name != 'pull_request'
uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
npm-cache/
node_modules/
dist/
book/.vitepress/cache/
*.pdf
*.epub
.DS_Store
1 change: 1 addition & 0 deletions .oxfmtrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
".agents/skills/**",
".claude/skills/**",
"dist/**",
"book/.vitepress/cache/**",
"pnpm-lock.yaml",
"skills-lock.json"
]
Expand Down
2 changes: 1 addition & 1 deletion .syncpackrc.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"$schema": "https://syncpack.dev/schema.json",
"source": ["package.json", "plugins/*/package.json"],
"source": ["package.json"],
"semverGroups": [
{
"dependencies": ["**"],
Expand Down
22 changes: 10 additions & 12 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,21 +11,20 @@ Operating guide for agents (and humans) working in this repository.
## Diagrams

- Diagrams are written as ```` ```mermaid ```` fences directly in the chapter, so the labels are translated together with the prose and GitHub renders them in the repo.
- `plugins/honkit-plugin-mermaid` renders the fences into inline SVG at build time (Mermaid in headless Playwright), so diagrams also survive `honkit pdf`, which never runs JS.
- [vitepress-mermaid](https://github.com/mokevnin/vitepress-mermaid) turns the fences into a `<Mermaid>` component that draws the diagram in the reader's browser and redraws it when dark mode is toggled. Rendering happens in the browser, so `mise run build` does not catch a Mermaid syntax error: open the page after editing a diagram and look for red source text (a `data-mermaid-error` element).
- Shared palette and theme live in `mermaid.config.json`. Use the `accent`, `warn` and `muted` classes (`node:::accent`) instead of per-diagram `classDef`.
- The website also gets every diagram in a dark palette for the Honkit night theme: `mermaid.config.dark.json` holds only the keys that differ and is merged over `mermaid.config.json`. A new color or class in the light config needs its dark counterpart there, including the `accent`/`warn`/`muted` rules in `themeCSS`. The PDF gets the light palette only.
- Rendered SVGs are cached in `node_modules/.cache/honkit-mermaid`, keyed by diagram source plus theme config. The theme is read once at startup, so restart `mise run serve` after editing `mermaid.config.json` or `mermaid.config.dark.json`.
- Dark mode uses a dark palette: `mermaid.config.dark.json` holds only the keys that differ and is merged over `mermaid.config.json` in `book/.vitepress/theme/mermaid-palette.mjs`. A new color or class in the light config needs its dark counterpart there, including the `accent`/`warn`/`muted` rules in `themeCSS`. `fontFamily` is ignored: diagrams use the page font.
- Beyond `flowchart`, the types that survive this pipeline and the palette are `sequenceDiagram`, `stateDiagram-v2`, `gitGraph`, `quadrantChart`, `pie` and `sankey-beta`.
- `sankey-beta` accepts **ASCII only in node names** (Mermaid 12.0.0) — quoting does not help, and Cyrillic or even Spanish accents raise a parse error. Its `title:` and `%%` comments do take non-ASCII. Where it is used, node labels stay English with a `%% TODO` to localize them once upstream is fixed.
- Types that silently drop the frontmatter `title:` the book uses as a caption: `sankey-beta`, `mindmap`, `timeline`, `kanban`, `block-beta`, `architecture-beta`. Put the thesis in the paragraph under the diagram instead. `treemap-beta` scales label size with box area, so the smallest — usually most important — share is the least readable.
- A diagram is read inside a ~770px column. Keep it under ~1200px wide — prefer `flowchart TB` over a long left-to-right chain, and remember that a note hung off a node with `-.-` widens the diagram.
- A diagram is read inside a ~690px column. Keep it under ~1200px wide — prefer `flowchart TB` over a long left-to-right chain, and remember that a note hung off a node with `-.-` widens the diagram.

## SEO and link previews

- `plugins/honkit-plugin-seo` post-processes the website build: it fills `meta description` from the chapter text, adds canonical, `hreflang` and Open Graph/Twitter tags, and writes `sitemap.xml`. PDFs are untouched.
- The public URL and preview image live in `pluginsConfig.seo` in `book/book.json`; change `baseUrl` there when the site moves to its own domain.
- `book/.vitepress/seo.mjs` adds per-page head tags in VitePress's `transformHead`: `meta description` from the chapter text, canonical, `hreflang` and Open Graph/Twitter tags. `sitemap.xml` is VitePress's own, with an x-default alternate added.
- The public URL, base path and preview image live in `book/.vitepress/config.mjs`; change `BASE_URL` and `base` there when the site moves to its own domain.
- The description is the first paragraph of a pattern's intent section, or an anti-pattern's problem section; other pages use their first paragraph, skipping an all-italic note. The section heading ids per locale are `descriptionSections` in the same config: add the id there when a new chapter kind opens differently. That paragraph should state the chapter's point on its own.
- Preview cards are `book/assets/og/<locale>.png`, rendered from `plugins/honkit-plugin-seo/og-card.html`; the command to rerender one is at the top of that file.
- Preview cards are `book/assets/og/<locale>.png`, rendered from `book/.vitepress/og-card.html`; the command to rerender one is at the top of that file.

## Markdown formatting

Expand Down Expand Up @@ -57,11 +56,10 @@ Operating guide for agents (and humans) working in this repository.

- Use mise 2026.11.3 or newer; CI pins 2026.11.8. Commit `mise.lock` alongside tool updates; it covers Linux x64 and macOS arm64.
- `mise run setup` — install locked deps, pinned linters and git hooks
- `mise run serve` — local preview (Honkit serve)
- `mise run build` — static build into `./dist`
- `pnpm exec playwright install chromium` — one-off, needed to render diagrams
- `mise run pdf` — PDFs for all locales
- `mise run update` — bump project tools and dependencies in every workspace package; when hk changes, also update both versioned Pkl imports in `hk.pkl`
- `mise run serve` — local preview with hot reload (VitePress dev server)
- `mise run build` — static build into `./dist`; VitePress fails it on a dead link between pages
- `mise run preview` — serve the `./dist` build locally
- `mise run update` — bump project tools and dependencies; when hk changes, also update both versioned Pkl imports in `hk.pkl`

## Structure conventions

Expand Down
10 changes: 5 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
# Contributing

The book is built from markdown with [Honkit](https://github.com/honkit/honkit). Navigation and grouping come from `book/<locale>/SUMMARY.md` — a separate file per language.
The book is built from Markdown with [VitePress](https://vitepress.dev/). Navigation and grouping come from `book/<locale>/SUMMARY.md` — a separate file per language; the site config turns it into the sidebar.

## Add a new pattern

0. Check [CANDIDATES.md](CANDIDATES.md) first. New ideas start there as a `candidate` row; adding a chapter means moving the idea to `accepted`. Rejected ideas stay documented so we don't reconsider them by accident.
1. Pick a kebab-case `slug` (e.g. `chain-of-thought`). It becomes the file name in every locale and the key under `book/assets/`.
2. Create the chapter in the canonical locale: copy [`templates/ru/pattern.md`](templates/ru/pattern.md) to `book/ru/<slug>.md` and fill it in. Do not change the section headings — they are the same across all chapters of that language.
3. Add a link in `book/ru/SUMMARY.md` under the right group heading (line order = order in the book).
4. Draw diagrams as ```` ```mermaid ```` fences right in the chapter — they are rendered to SVG at build time and translated together with the surrounding text. Use the shared `accent` / `warn` / `muted` classes (`node:::accent`) so every diagram in the book shares one palette; the theme lives in `mermaid.config.json`, and its night-theme counterpart in `mermaid.config.dark.json`.
4. Draw diagrams as ```` ```mermaid ```` fences right in the chapter — they are drawn in the reader's browser by [vitepress-mermaid](https://github.com/mokevnin/vitepress-mermaid) and translated together with the surrounding text. The build does not catch a syntax error, so check the page in `mise run serve`. Use the shared `accent` / `warn` / `muted` classes (`node:::accent`) so every diagram in the book shares one palette; the theme lives in `mermaid.config.json`, and its dark-mode counterpart in `mermaid.config.dark.json`.
5. Anything that is genuinely a file — images, sample code — goes in `book/assets/<slug>/` and is referenced with a relative path `../assets/<slug>/...`.
6. Preview with `pnpm start`.
6. Preview with `mise run serve`.

## Extend an existing pattern

Expand All @@ -29,7 +29,7 @@ Recheck a tool profile against the tool's primary documentation before each book

## Chapter front matter (optional but useful)

Honkit takes the title from the first `#` and navigation from `SUMMARY.md`. A small front matter is handy as metadata and reads well on GitHub:
VitePress takes the title from the first `#` and navigation from `SUMMARY.md`. A small front matter is handy as metadata and reads well on GitHub. Avoid keys VitePress reserves (`title`, `description`, `layout`, `outline`, `sidebar` and the like) unless you mean to override the page:

```yaml
---
Expand All @@ -42,7 +42,7 @@ source_rev: # for NON-canonical locales only (see below)

## Translation

- The canonical locale is `ru` (`language` in `book/book.json`). A pattern is written in Russian first.
- The canonical locale is `ru`. A pattern is written in Russian first.
- To translate, copy `book/ru/<slug>.md` to `book/<locale>/<slug>.md`, translate the text, and add a link to `book/<locale>/SUMMARY.md` in the same group. Use the matching template under `templates/<locale>/` for the localized headings.
- In the translation's front matter set `source_rev` — the git SHA of the ru chapter at the time of translating, so staleness can be tracked:

Expand Down
23 changes: 10 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,6 @@
# Agentic Coding Design Patterns

A catalog of patterns in the spirit of the "Gang of Four" (GoF) about **how a
developer works with an AI agent when writing code**. It is a book built from
markdown with [Honkit](https://github.com/honkit/honkit) (a GitBook fork), with
print (PDF/EPUB) in mind.
A catalog of patterns in the spirit of the "Gang of Four" (GoF) about **how a developer works with an AI agent when writing code**. It is a book written in Markdown and published as a website with [VitePress](https://vitepress.dev/).

📖 **Online:** <https://mokevnin.github.io/agentic-coding-design-patterns/>

Expand All @@ -12,11 +9,11 @@ print (PDF/EPUB) in mind.
## Repository layout

```text
book/ — the book root (Honkit)
book.json — Honkit config
LANGS.md — list of languages (Honkit multilingual)
book/ — the book root (VitePress source directory)
.vitepress/ — site config: locales, sidebar, SEO, theme and Mermaid palette
README.md — language picker at the site root
<locale>/
SUMMARY.md — table of contents: groups = headings, patterns = links
SUMMARY.md — table of contents: groups = headings, patterns = links; builds the sidebar
README.md — locale landing page
<slug>.md — a chapter (flat list, no group folders)
assets/<slug>/ — diagrams and code samples shared across languages
Expand All @@ -36,17 +33,17 @@ same across all locales.
## Development

```sh
mise run setup # locked toolchain, workspace dependencies and git hooks
mise run serve # local preview (honkit serve)
mise run setup # locked toolchain, dependencies and git hooks
mise run serve # local preview with hot reload (VitePress dev server)
mise run check # the same quality gates as CI
mise run build # static build into ./dist
mise run pdf # PDFs for all locales (requires Calibre/ebook-convert)
mise run update # update project tools and all workspace dependencies
mise run preview # serve the ./dist build locally
mise run update # update project tools and dependencies
```

Use [mise](https://mise.jdx.dev/) 2026.11.3 or newer; CI pins 2026.11.4. Node is pinned in `mise.toml`; mise reads pnpm from `package.json`. `mise.lock` records tool downloads and checksums for Linux x64 and macOS arm64. Both setup and CI install from the committed lockfiles. After updating hk, update the two versioned Pkl imports in `hk.pkl` as well.

The [Dev Quality Gates](https://github.com/mokevnin/dev-quality-gates) checks run through `hk.pkl`: code lint and formatting, workspace dependency consistency, Markdown, spelling, agent configuration, workflow security, secrets, local documentation links, conflict markers, filename case collisions and broken symlinks. Local links are checked offline so commits do not depend on external websites. Known dependency vulnerabilities are checked by the scheduled audit workflow.
The [Dev Quality Gates](https://github.com/mokevnin/dev-quality-gates) checks run through `hk.pkl`: code lint and formatting, unit tests for the site config, dependency range consistency, Markdown, spelling, agent configuration, workflow security, secrets, local documentation links, conflict markers, filename case collisions and broken symlinks. Local links are checked offline so commits do not depend on external websites. Known dependency vulnerabilities are checked by the scheduled audit workflow.

- How to add a pattern and how translations work — see [CONTRIBUTING.md](CONTRIBUTING.md).
- The canonical locale is `ru`: a pattern is first written in Russian, then
Expand Down
Loading