/CLAUDE.md

CLAUDE.md at /CLAUDE.md

Path: CLAUDE.md

zudo-tauri-wisdom

Takazudo's Tauri v2 dev notes, built with zudo-doc (zfb stack, MDX, zudo-react and zudo-wind).

Commands

Use Node.js 24 (>=24 <25) and the pnpm version pinned in package.json.

pnpm dev              # Start dev: zfb dev server (port 4321) + doc-history-server (4322), via run-p
pnpm build            # Build static site via zfb build
pnpm preview          # Preview built site
pnpm check            # zfb type checking
pnpm check:html       # Validate built HTML (html-validate dist/**/*.html)
pnpm check:links      # Check for broken links in dist/
pnpm check:pin-parity # Verify pin version parity across packages
pnpm check:wrangler-pin # Verify wrangler version is pinned correctly
pnpm check:template-drift # Check for template drift vs upstream
pnpm format:md        # Format MDX files (write)
pnpm format:md:check  # Format MDX files (check only)
pnpm b4push           # Pre-push validation (format + drift + pins + typecheck + build + html + links)
pnpm setup:doc-skill  # Generate tauri-wisdom skill + symlink all skills

zudo-doc 7.x note: doc-history now runs as a separate process (dev:history), so pnpm dev uses run-p to launch it alongside zfb dev. z-index tokens are package-owned in 7.x, so the old gen:z-index / check:z-index scripts are gone.

Content Structure

• English (default): src/content/docs/ -> /docs/...

• Japanese: src/content/docs-ja/ -> /ja/docs/...

• Japanese docs should mirror the English directory structure

Bilingual rule: When creating or updating any doc page, ALWAYS update both the English (docs/) and Japanese (docs-ja/) versions in the same PR. Keep code blocks identical between languages -- only translate surrounding prose. If a Japanese version does not yet exist, create it.

Exception: Pages with generated: true in frontmatter (e.g., claude-resources auto-generated pages) do not require Japanese translations.

Content Categories

Top-level directories under src/content/docs/. Directories with header nav entries are mapped via categoryMatch in the headerNav of zfb.config.ts:

• getting-started/ - Overview, project setup, dev vs production mode

• architecture/ - Sidecar pattern, loading screen, process lifecycle

• rust-backend/ - Mutex safety, settings cache, file watchers, menus, windows

• frontend/ - IPC commands, useEffect pitfalls, capabilities

• dev-server/ - SSE live-reload, watcher loops, Vite integration

• deployment/ - Build bundle, macOS pitfalls, cargo cache, node download

• mobile/ - Mobile (iOS/Android) Tauri setup and patterns

• recipes/ - Real-world app patterns (doc viewer, text editor, multi-config)

• claude/ - Claude Code integration docs

Auto-generated directories (no header nav entry, managed by claude-resources integration):

• claude-md/ - CLAUDE.md file documentation (noPage: true)

• claude-skills/ - Claude Skills documentation (noPage: true)

Writing Docs

All documentation files use .mdx format with YAML frontmatter.

Frontmatter Fields

The whole site is configured through a single zudoDoc({...}) call in zfb.config.ts (zudo-doc 7.x single-entry config API). The frontmatter schema and content collections are package-owned defaults (@takazudo/zudo-doc) — there is NO src/config/docs-schema.ts and NO src/content.config.ts. To override the schema, pass buildDocsSchema to zudoDoc().

Content Rules

• No h1 in content: The frontmatter title is automatically rendered as the page h1. Start your content with ## h2 headings. Do not write # h1 in the MDX body.

• Always set sidebar_position: Without it, pages sort alphabetically which is unpredictable. Use integers starting from 1.

• Kebab-case file names: Use my-article.mdx, not myArticle.mdx or my_article.mdx.

Linking Between Docs

Use relative file paths with the .mdx extension:

[Link text](./sibling-page.mdx)
[Link text](../other-category/page.mdx)
[Link text](../other-category/page.mdx#anchor)

The remark plugin resolves these during build. External links use standard URLs.

Admonitions

Available globally without imports. Two syntax forms:

Directive syntax (preferred for longer content):

:::note[Custom Title]
Content here.
:::

JSX syntax (for inline use):

<Note>Short note content.</Note>

Types: <Note>, <Tip>, <Info>, <Warning>, <Danger>, <Caution>

Additional directive types:

:::details[Summary text]
Collapsible content here.
:::

:::code-group
```bash [npm]
npm install
```
```bash [pnpm]
pnpm install
```
:::

:::caution
Caution content here.
:::

Mermaid Diagrams

Mermaid is enabled. Use fenced code blocks:

```mermaid

graph TB
  A --> B

```

HtmlPreview Component

For interactive HTML/CSS/JS previews with code display:

<HtmlPreview html="<div>Hello</div>" css="div { color: red; }" />

Use js/displayJs props for JavaScript demos.

Navigation Structure

Navigation is filesystem-driven. Directory structure directly becomes sidebar navigation.

Sidebar Ordering

• Pages are ordered by sidebar_position (ascending). Without it, alphabetical order is used.

• Category index pages (index.mdx) control category position via their own sidebar_position.

Category Index Pages

Create index.mdx in a category directory when you want custom intro copy, description, or explicit sidebar ordering. The framework auto-generates category index pages when missing, but explicit ones give better control.

Category Configuration

Use _category_.json for category-level metadata when needed:

{
  "label": "Category Name",
  "position": 900,
  "description": "Category description",
  "noPage": true
}

The noPage: true flag means the category has no landing page (just groups items). Alternatively, use category_no_page: true in the index.mdx frontmatter -- frontmatter wins over the sidecar JSON.

Header Navigation

Defined in the zudoDoc({...}) call in zfb.config.ts via headerNav. Each item maps to a top-level content directory via categoryMatch:

{ label: "Overview", path: "/docs/getting-started", categoryMatch: "getting-started" }

categoryMatch must be a single top-level directory name. Adding a new header nav item requires editing zfb.config.ts.

Content Creation Workflow

Adding a New Article

1. Create the English .mdx file in the appropriate category under src/content/docs/

2. Add frontmatter with at least title and sidebar_position

3. Write content starting with ## h2 headings (not # h1)

4. Create the matching Japanese file under src/content/docs-ja/ with the same path

5. Keep code blocks, Mermaid diagrams, and <HtmlPreview> blocks identical -- only translate prose

6. Run pnpm format:md to format the MDX files

7. Run pnpm build to verify the site builds correctly

Adding a New Category

1. Create the directory under src/content/docs/ (kebab-case)

2. Create index.mdx with title, description, and sidebar_position

3. Add a headerNav entry in zfb.config.ts with categoryMatch pointing to the directory name

4. Mirror the directory structure under src/content/docs-ja/

5. Run pnpm build to verify

MDX Components

Available globally in MDX without imports:

• <Note>, <Tip>, <Info>, <Warning>, <Danger>, <Caution> - Admonitions

• <HtmlPreview> - Interactive HTML/CSS/JS preview with code display

Typography

• Futura for page h1 titles and header site name (font-futura class)

• Noto Sans JP for body text

• Headings use font-weight 400 (normal), not bold

Doc Skill (tauri-wisdom)

The tauri-wisdom skill (.claude/skills/tauri-wisdom/SKILL.md) is generated by pnpm setup:doc-skill (runs scripts/setup-doc-skill.sh). It is gitignored -- do NOT track it in git or edit it directly. To update the skill content, edit the generator script and re-run pnpm setup:doc-skill.

Project Layout

The zudo-doc 7.x host surface is provided by the @takazudo/zudo-doc package (config API, components, utils, types, route helpers, design tokens are all package-owned). The project ships only a thin shell:

pages/                    # 3 route stubs only (rest injected by the package)
  index.tsx               #   1-line re-export of the package home route
  docs/[[...slug]].tsx    #   self-contained doc-route stub with DocHistoryBoundary
  [locale]/docs/[[...slug]].tsx  # locale-prefixed counterpart (i18n)
src/
  content/                # MDX doc pages (docs/ + docs-ja/) — the actual content
  styles/global.css       # package CSS imports + host font/brand overrides
zfb.config.ts             # the ONE config file: a single zudoDoc({...}) call
setup-preset.json         # scaffold config record (drives re-scaffold)
scripts/                  # host check/gen scripts (drift, pins, links, doc-skill)

Site Config

• Base path: / (root — no subpath prefix)

• Live URL: https://zudo-tauri-wisdom.takazudomodular.com/

• Config: zfb.config.ts — the entire site config is one zudoDoc({...}) call (@takazudo/zudo-doc/config); there is no src/config/settings.ts in 7.x

CI/CD

• PR checks: typecheck + build + Cloudflare Workers static assets preview

• Main deploy: build -> wrangler deploy -> Cloudflare Workers + IFTTT notification

• Hosting: Cloudflare Workers static assets (not Pages)

• Secrets: CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN, IFTTT_PROD_NOTIFY