/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, Tailwind CSS v4).

Commands

pnpm dev              # Start zfb dev server (port 4321)
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 + typecheck + build)
pnpm gen:z-index      # Generate z-index tokens
pnpm check:z-index    # Check z-index tokens are up to date
pnpm setup:doc-skill  # Generate tauri-wisdom skill + symlink all skills

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 src/config/settings.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

Schema defined in zfb.config.ts (collections) and src/config/docs-schema.ts (field definitions). There is NO src/content.config.ts -- collections live in zfb.config.ts.

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

pnpm install

:::

### Mermaid Diagrams

Mermaid is enabled. Use fenced code blocks:

````markdown
```mermaid

graph TB
  A --> B

### HtmlPreview Component

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

```markdown
<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:

```json
{
  "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 `src/config/settings.ts` via `headerNav`. Each item maps to a top-level content directory via `categoryMatch`:

```typescript
{ 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 `settings.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 `src/config/settings.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

```
pages/          # Host-app routing layer (zfb entry points)
src/
  components/   # Shared UI components
  config/       # settings.ts — site-wide config; docs-schema.ts — frontmatter schema
  content/      # MDX doc pages (docs/ + docs-ja/)
  utils/        # Shared utilities
plugins/        # zfb integration plugins (.mjs)
zfb.config.ts   # Build config (framework, collections, plugins, adapter)
```

## Site Config

- Base path: `/` (root — no subpath prefix)
- Live URL: `https://zudo-tauri-wisdom.takazudomodular.com/`
- Settings: `src/config/settings.ts`
- Build config: `zfb.config.ts`

## 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`