Chapter 09 — Holy Book on Ocarina — manual

09.01 — VitePress + Sugar Theme + in-house plugins stack

Wed, 20 May 2026 00:00:00 +0000

09.01 — VitePress + Sugar Theme + in-house plugins stack#

`package.json`#

{
  "dependencies": {
    "@sugarat/theme": "0.5.17"
  },
  "devDependencies": {
    "@commitlint/config-conventional": "20.5.0",
    "@commitlint/cz-commitlint": "20.5.1",
    "@eslint/js": "10.0.1",
    "@types/node": "25.6.0",
    "commitizen": "4.3.1",
    "editorconfig": "3.0.2",
    "eslint": "10.2.1",
    "eslint-plugin-import-x": "4.16.2",
    "eslint-plugin-perfectionist": "5.9.0",
    "eslint-plugin-unused-imports": "4.4.1",
    "globals": "17.5.0",
    "husky": "9.1.7",
    "inquirer": "9.0.0",
    "is-ci": "4.1.0",
    "lint-staged": "16.4.0",
    "pagefind": "1.5.2",
    "prettier": "3.8.3",
    "sass-embedded": "1.99.0",
    "typescript": "6.0.3",
    "typescript-eslint": "8.59.0",
    "vitepress": "2.0.0-alpha.17",
    "vitepress-plugin-image-optimize": "1.5.1",
    "vue": "3.5.33"
  },
  "engines": {
    "node": "^24.x",
    "pnpm": "11.x"
  }
}

Lib	Role
`vitepress 2.0.0-alpha.17`	SSG framework, Vite-based
`@sugarat/theme`	First-class blog theme (templates, auto sidebar, covers)
`vue 3.5.33`	Required by VitePress
`vitepress-plugin-image-optimize`	Build-time image optimization
`pagefind 1.5.2`	Static search engine (full-text, side-CDN)
`sass-embedded`	Compiles SCSS (used by `@sugarat/theme`)
Husky / lint-staged / commitlint	Same tools as the other repos (Conventional Commits)

`docs/.vitepress/config.mts`#

import { defineConfig } from 'vitepress';
import path from 'path';
import fs from 'fs';

import { generateSkills } from './plugins/skills';
import { generateLlms } from './plugins/llm';
import { generatePub } from './plugins/pub';
import { blogTheme } from './blog-theme';
import webpConfig from './plugins/webp';

const base = process.env.GITHUB_ACTIONS === 'true' ? '/ocarina-holy-book/' : '/';

export default defineConfig({
  locales: {
    root: {
      themeConfig: {
        outline: { label: 'Table of content' },
        skipToContentLabel: 'Skip to content',
        sidebarMenuLabel: 'Related articles',
        returnToTopLabel: 'Return to top',
        lastUpdatedText: 'Last update:'
      },
      description: "Ocarina is Igor's automated web browser testing framework.",
      title: 'The Ocarina Holy Book',
      label: 'English',
      lang: 'en'
    },
    fr: {
      themeConfig: {
        outline: { label: 'Sommaire', level: [2, 3] },
        returnToTopLabel: 'Retour en haut de page',
        lastUpdatedText: 'Dernière mise à jour :',
        skipToContentLabel: 'Passer au contenu',
        sidebarMenuLabel: 'Voir aussi'
      },
      title: "Le livre sacré d'Ocarina",
      label: 'Français',
      lang: 'fr'
    }
    ru: {
      themeConfig: {
        outline: {
          label: 'Оглавление',
          level: [2, 3]
        },
        skipToContentLabel: 'Перейти к содержанию',
        lastUpdatedText: 'Последнее обновление:',
        returnToTopLabel: 'Вернуться вверх',
        sidebarMenuLabel: 'Смотрите также'
      },
      title: 'Священная Книга Ocarina',
      label: 'Русский',
      lang: 'ru'
    }
  },
  vite: { ... },
  ...
});

1. `base`#

const base =
  process.env.GITHUB_ACTIONS === "true" ? "/ocarina-holy-book/" : "/";

In CI (GitHub Actions): base = /ocarina-holy-book/ (GitHub Pages prefix). Locally: / (served from the dev server root).

09.02 — I18n FR/EN/RU

Wed, 20 May 2026 00:00:00 +0000

09.02 — I18n FR/EN/RU#

Every Holy Book page exists in three versions. EN at the root of docs/, FR under docs/fr/, RU under docs/ru/. VitePress routes automatically.

File structure#

docs/
├── index.md                                                        # EN home
├── what-is-it.md
├── first-feedbacks.md
├── setup.md
├── scenarios-composability.md
├── datasets-smoke-tests-setup-teardown-proxy-api-and-caching.md
├── handling-flakiness.md
├── extensibility.md
├── using-ocarina-with-ai.md
│
├── fr/
│   ├── index.md                                                    # FR home
│   ├── what-is-it.md
│   ├── first-feedbacks.md
│   ├── setup.md
│   ├── scenarios-composability.md
│   ├── datasets-smoke-tests-setup-teardown-proxy-api-and-caching.md
│   ├── handling-flakiness.md
│   ├── extensibility.md
│   └── using-ocarina-with-ai.md
│
├── ru/
│   ├── index.md                                                    # RU home
│   ├── what-is-it.md
│   ├── first-feedbacks.md
│   ├── setup.md
│   ├── scenarios-composability.md
│   ├── datasets-smoke-tests-setup-teardown-proxy-api-and-caching.md
│   ├── handling-flakiness.md
│   ├── extensibility.md
│   └── using-ocarina-with-ai.md
│
├── public/
│   ├── favicon.ico
│   ├── logo.png
│   ├── robots.txt
│   ├── .nojekyll
│   ├── .spa
│   └── assets/
│       └── content/
│           └── ...                                                 # shared EN+FR+RU images
│
└── .vitepress/
    ├── config.mts
    ├── blog-theme.ts
    ├── shims.d.ts
    ├── plugins/
    │   ├── llm.ts
    │   ├── pub.ts
    │   ├── skills.ts
    │   └── webp.ts
    └── theme/
        ├── index.ts
        ├── style.css
        ├── user-theme.css
        ├── components/
        │   ├── Pagination.vue
        │   ├── BlogHomeBanner.vue
        │   └── NotFound.vue
        └── assets/
            └── bg.png

Routing#

Page	URL EN	URL FR	URL RU
Home	`/`	`/fr/`	`/ru/`
Pitch	`/what-is-it`	`/fr/what-is-it`	`/ru/what-is-it`
Rant	`/first-feedbacks`	`/fr/first-feedbacks`	`/ru/first-feedbacks`
Setup	`/setup`	`/fr/setup`	`/ru/setup`
…	…	…	…

VitePress auto-builds the language switcher (top right). Clicking “FR” from /setup takes you to /fr/setup.

09.04 — CLAUDE.md and CLAUDE.slim.md

Wed, 20 May 2026 00:00:00 +0000

09.04 — `CLAUDE.md` and `CLAUDE.slim.md`#

The Holy Book actively publishes the CLAUDE.md files. This lets an LLM fetch the project’s docs without going through the repo.

The two files#

ai/
├── CLAUDE.md       # full version (rules + project layout)
└── CLAUDE.slim.md  # short version (rules only)

Public URLs#

https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.md
https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.slim.md

Holy Book quote (chapter “Using Ocarina with AI”):

Slim when context is heavy; full for onboarding and reviews. Full wins on disagreement.

09.05 — PDF generation (generate-books)

Wed, 20 May 2026 00:00:00 +0000

09.05 — PDF generation (`generate-books`)#

The public PDFs (ocarina-ru.pdf, ocarina-en.pdf, ocarina-fr.pdf…) are AI-generated from the docs/ folder, a Python script, and a Markdown prompt.

Tree#

prompts/generate-books/
├── prompt.md                     # spec (read by the AI)
├── script.py                     # Python implementation
├── NotoSans-Regular.ttf
├── NotoSans-Bold.ttf
├── NotoSans-Italic.ttf
├── NotoSans-BoldItalic.ttf
├── NotoSansMath-Regular.ttf
├── NotoSansMono-Regular.ttf
├── NotoSansSymbols2-Regular.ttf
├── NotoNaskhArabic-Regular.ttf
└── NotoColorEmoji-Regular.ttf

1. A `prompt.md` + a `script.py`#

prompt.md:

Ocarina PDF Generator#

What this is#

A system that turns a VitePress docs/ folder (Markdown + images) into three polished A4 PDFs — one Russian, one English, one French. The system is two files: this prompt (the spec) and script.py (the implementation). They are designed to be used together in an agentic environment.

09.06 — Public resources

Wed, 20 May 2026 00:00:00 +0000

09.06 — Public resources#

Full table of public URLs exposed by the Holy Book. For humans, LLMs, scrapers.

Listing (potentially non-exhaustive)#

URL	Content	Target audience
`https://mojo-molotov.github.io/ocarina-holy-book/`	Home (EN)	Human
`https://mojo-molotov.github.io/ocarina-holy-book/fr/`	Home (FR)	Human
`https://mojo-molotov.github.io/ocarina-holy-book/ru/`	Home (RU)	Human
`https://mojo-molotov.github.io/ocarina-holy-book/what-is-it`	Article (EN)	Human
`https://mojo-molotov.github.io/ocarina-holy-book/fr/what-is-it`	Article (FR)	Human
`https://mojo-molotov.github.io/ocarina-holy-book/ru/what-is-it`	Article (RU)	Human
… (other doc pages in EN+FR+RU)	…	Human
`https://mojo-molotov.github.io/ocarina-holy-book/llms.txt`	Minimal index for LLMs	LLM
`https://mojo-molotov.github.io/ocarina-holy-book/llms-full.txt`	All content in plaintext	LLM, scraper
`https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.md`	Full project rules	LLM, human (onboarding)
`https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.slim.md`	Short project rules	LLM (context budget)
`https://mojo-molotov.github.io/ocarina-holy-book/ocarina-en.pdf`	A4 PDF docs (EN)	Human (offline)
`https://mojo-molotov.github.io/ocarina-holy-book/ocarina-fr.pdf`	A4 PDF docs (FR)	Human (offline)
`https://mojo-molotov.github.io/ocarina-holy-book/ocarina-ru.pdf`	A4 PDF docs (RU)	Human (offline)
`https://mojo-molotov.github.io/ocarina-holy-book/skills/<name>`	AI skill page	Human, LLM
`https://mojo-molotov.github.io/ocarina-holy-book/assets/content/...`	Images, audio (article covers, illustrations)	Human (inline rendering)

`llms.txt` (emerging standard)#

Spec: https://llmstxt.org/ (proposed in 2024).

Chapter 09 — Holy Book on Ocarina — manual

09.01 — VitePress + Sugar Theme + in-house plugins stack

09.01 — VitePress + Sugar Theme + in-house plugins stack#

package.json#

docs/.vitepress/config.mts#

1. base#

09.02 — I18n FR/EN/RU

09.02 — I18n FR/EN/RU#

File structure#

Routing#

09.04 — CLAUDE.md and CLAUDE.slim.md

09.04 — CLAUDE.md and CLAUDE.slim.md#

The two files#

Public URLs#

09.05 — PDF generation (generate-books)

09.05 — PDF generation (generate-books)#

Tree#

1. A prompt.md + a script.py#

Ocarina PDF Generator#

What this is#

09.06 — Public resources

09.06 — Public resources#

Listing (potentially non-exhaustive)#

llms.txt (emerging standard)#

`package.json`#

`docs/.vitepress/config.mts`#

1. `base`#

09.04 — `CLAUDE.md` and `CLAUDE.slim.md`#

09.05 — PDF generation (`generate-books`)#

1. A `prompt.md` + a `script.py`#

`llms.txt` (emerging standard)#