===============
LIBRARY RULES
===============
From library maintainers:
- Always use zdoc.config.json instead of config.json when referring to the configuration file
- Include -t/--title option in CLI usage documentation
- The configuration file is named zdoc.config.json not config.json
- CLI supports flags: -d/--docs, -p/--port, -w/--password, -t/--title

### zdoc CLI Examples

Source: https://github.com/o7z/zdoc/blob/main/README.md

Examples demonstrating various ways to run the zdoc CLI with different configurations.

```bash
zdoc                                # cwd, port 8888, no password (public)
zdoc -d ./docs -p 3000              # custom dir and port
zdoc -t "My Docs"                   # custom site title
zdoc -w hunter2                     # enable password protection
zdoc -w hunter2 -p 8080 -d ./site   # full override
```

--------------------------------

### Zdoc Command-Line Examples

Source: https://github.com/o7z/zdoc/blob/main/README.zh-CN.md

Examples demonstrating how to use zdoc with various command-line arguments to specify directories, ports, and enable password protection.

```bash
zdoc                                # 当前目录，端口 8888，无密码（公开）
zdoc -d ./docs -p 3000              # 自定义目录和端口
zdoc -w hunter2                     # 启用密码保护
zdoc -w hunter2 -p 8080 -d ./site   # 全参数覆盖
```

--------------------------------

### Install and Run @o7z/zdoc

Source: https://github.com/o7z/zdoc/blob/main/README.zh-CN.md

Use npx to run zdoc directly from the command line in a directory containing Markdown files. Alternatively, install it globally for direct access.

```bash
# 在任意包含 Markdown 文件的目录：
npx @o7z/zdoc
# 或全局安装：
npm i -g @o7z/zdoc
zdoc
```

--------------------------------

### Directory Structure Example

Source: https://github.com/o7z/zdoc/blob/main/README.zh-CN.md

An example illustrating a typical directory structure for a zdoc project, including `_meta.yaml` files, Markdown documents, and PDF files.

```text
docs/
├── _meta.yaml              # title: 我的文档
├── index.md                # 站点首页（纯 Markdown）
├── getting-started/
│   ├── _meta.yaml          # title: 快速开始; order: 1; pages: {install:…, config:…}
│   ├── install.md          # 纯内容，在 _meta.yaml 里列出
│   └── config.md
├── guide/
│   ├── _meta.yaml          # title: 指南; order: 2; pages: {basics:…, advanced:…}
│   ├── basics.md
│   └── advanced.md
└── reports/
    ├── _meta.yaml          # title: 报告; order: 3; pages: {Q4.pdf: {title: Q4 报告}}
    └── Q4.pdf
```

--------------------------------

### Install and Run zdoc

Source: https://github.com/o7z/zdoc/blob/main/README.md

Install the package globally or run it directly using npx. By default, it serves the current directory on port 8888 without a password.

```bash
npx @o7z/zdoc
# or install globally:
npm i -g @o7z/zdoc
zdoc
```

--------------------------------

### Development Commands

Source: https://github.com/o7z/zdoc/blob/main/README.md

Provides commands for installing dependencies, running Zdoc in development mode, and building the project.

```bash
bun install
bun run dev        # zdoc rendering its own docs/ (the official site)
bun run dev:demo   # zdoc rendering demo/ (regression samples only)
bun run dev:vite   # raw vite dev, no ZDOC_DIR preset
bun run build      # produce build/ + bin/cli.js
node bin/cli.js -d ./some/docs
```

--------------------------------

### Example Project Structure

Source: https://github.com/o7z/zdoc/blob/main/README.md

Illustrates the directory layout for a Zdoc project, including metadata files and content organization.

```tree
docs/
├── _meta.yaml              # title: My Docs
├── index.md                # site home (plain Markdown)
├── getting-started/
│   ├── _meta.yaml          # title: Getting Started; order: 1; pages: {install:…, config:…}
│   ├── install.md          # pure content, listed in _meta.yaml
│   └── config.md
├── guide/
│   ├── _meta.yaml          # title: Guide; order: 2; pages: {basics:…, advanced:…}
│   ├── basics.md
│   └── advanced.md
└── reports/
    ├── _meta.yaml          # title: Reports; order: 3; pages: {Q4.pdf: {title: Q4 Report}}
    └── Q4.pdf
```

--------------------------------

### Zdoc Configuration File Example

Source: https://github.com/o7z/zdoc/blob/main/README.zh-CN.md

Configure default settings for zdoc by creating a `config.json` file in the directory where zdoc is run. This allows setting the title, documentation directory, password, and port.

```json
{
  "title": "我的文档",
  "docsDir": "./docs",
  "password": "hunter2",
  "port": 8888
}
```

--------------------------------

### zdoc Configuration File

Source: https://github.com/o7z/zdoc/blob/main/README.md

Example of a `zdoc.config.json` file used to set default server configurations. CLI flags override these settings.

```json
{
  "title": "My Docs",
  "docsDir": "./docs",
  "password": "hunter2",
  "port": 8888
}
```

--------------------------------

### YAML Metadata for Sidebar

Source: https://github.com/o7z/zdoc/blob/main/README.md

Example of a `_meta.yaml` file used to define the sidebar structure, page titles, order, and other metadata for a directory.

```yaml
title: Getting Started      # required — sidebar label for the directory
order: 1                     # optional — sort weight (lower = earlier). Default 999
env: prod                    # optional — set to "prod" to hide in non-prod

pages:
  install:
    title: Install           # required — without this, the file is hidden
    order: 1
    modified: 2026-04-18
    version: 1.0.1
    description: Step-by-step install for npm, bun, and global use.
    author: o7z
  config:
    title: Config
    order: 2
  report.pdf:                # PDFs: use the full filename including extension
    title: Q4 Report
    order: 3
```

--------------------------------

### Markdown Hero Frontmatter Example

Source: https://github.com/o7z/zdoc/blob/main/README.zh-CN.md

Enhance the root `index.md` file with YAML frontmatter to create a hero section for your documentation site, including project name, tagline, actions, and features.

```markdown
---
name: 我的项目
text: 最快的文档站方案
tagline: 零配置，暗色模式，Mermaid，搜索。
actions:
  - theme: brand
    text: 快速开始
    link: /getting-started/install.md
  - theme: alt
    text: GitHub
    link: https://github.com/…
features:
  - title: 零配置
    details: 丢到任意 Markdown 目录就能跑。
  - title: 密码保护
    details: 服务端会话鉴权，运行时可改密码。
---

# 欢迎

frontmatter 之后的 Markdown 正常渲染。
```

--------------------------------

### Zdoc Command-Line Options

Source: https://github.com/o7z/zdoc/blob/main/README.zh-CN.md

Understand the available command-line arguments for customizing zdoc's behavior, including directory, port, and password settings.

```bash
zdoc [options]

Options:
  -d, --dir <path>       Markdown 文档目录（默认：当前工作目录）
  -p, --port <number>    监听端口（默认：8888；被占用时自动递增）
  -w, --password <pwd>   访问密码（默认：无密码，文档公开；设置后启用密码保护）
  -h, --help             显示帮助信息
  -v, --version          显示版本号
```

--------------------------------

### zdoc CLI Options

Source: https://github.com/o7z/zdoc/blob/main/README.md

Command-line interface options for configuring the zdoc server, including directory, port, title, and password.

```bash
zdoc [options]

Options:
  -d, --dir <path>       Markdown docs directory (default: current working directory)
  -p, --port <number>    Port to listen on (default: 8888, auto-increments if busy)
  -t, --title <string>   Site title (default: Docs)
  -w, --password <pwd>   Access password (default: none, docs are public; set to enable auth)
  -h, --help             Show help
  -v, --version          Show version
```

--------------------------------

### index.md 纯 Markdown 示例

Source: https://github.com/o7z/zdoc/blob/main/docs/authoring/links-and-routes.md

文档根目录的 index.md 文件也可以不加 frontmatter，直接以纯 Markdown 内容作为项目文档首页。

```markdown
# 项目名称

> 一句话描述

## 目录

1. [愿景](/01-vision)
2. [架构](/02-architecture)
```

--------------------------------

### index.md Hero Frontmatter 示例

Source: https://github.com/o7z/zdoc/blob/main/docs/authoring/links-and-routes.md

文档根目录的 index.md 文件可以使用 hero frontmatter 来渲染产品首页，包含项目名称、描述、行动链接等。

```markdown
---
name: My Project
text: 一句话描述
tagline: 补充说明
actions:
  - theme: brand
    text: 开始
    link: /intro/getting-started
features:
  - title: 特性一
    details: 描述
---

# 欢迎

frontmatter 下方可以继续写普通 Markdown。
```

--------------------------------

### index.md 路由示例

Source: https://github.com/o7z/zdoc/blob/main/docs/authoring/links-and-routes.md

子目录下的 index.md 文件路由为 /<目录>/index。链接时需包含 /index。

```markdown
[模块总览](/02-modules/index)
```

--------------------------------

### Hero Frontmatter 链接示例

Source: https://github.com/o7z/zdoc/blob/main/docs/authoring/links-and-routes.md

在 index.md 文件的 hero frontmatter 中，actions.link 的值也应遵循不带 .md 后缀的路由规则。

```yaml
actions:
  - theme: brand
    text: 开始
    link: /intro/what-is-zdoc    # ✅ 不带 .md
```

--------------------------------

### Markdown 内部链接示例

Source: https://github.com/o7z/zdoc/blob/main/docs/authoring/links-and-routes.md

在 Markdown 文件中，使用绝对路径且不带 .md 后缀来引用内部链接。相对路径加 .md 后缀会导致 404 错误。

```markdown
<!-- ✅ 正确 -->
[安装指南](/getting-started/install)
[API 参考](/api/rest)

<!-- ❌ 错误 —— 会 404 -->
[安装指南](./install.md)
[API 参考](../api/rest.md)
```

--------------------------------

### Meta YAML Structure for Sidebar

Source: https://github.com/o7z/zdoc/blob/main/README.zh-CN.md

Define the structure and metadata for your documentation site's sidebar using `_meta.yaml` files within each directory. This includes directory titles, ordering, and listing of Markdown and PDF files.

```yaml
title: 快速开始              # 必填 —— 侧边栏显示的目录名
order: 1                    # 可选 —— 排序权重（越小越靠前），默认 999
env: prod                   # 可选 —— 设为 "prod" 表示仅生产环境显示

pages:
  install:                  # key = 去掉 .md 的文件名
    title: 安装             # 必填，没有则该文件隐藏
    order: 1
    modified: 2026-04-18
    version: 1.0.1
    description: npm、bun 以及全局安装的分步指南。
    author: o7z
  config:
    title: 配置
    order: 2
  report.pdf:               # PDF 文件：key 保留完整文件名（含扩展名）
    title: 第四季度报告
    order: 3
```

--------------------------------

### Markdown Frontmatter for Index Page

Source: https://github.com/o7z/zdoc/blob/main/README.md

Defines the hero section and metadata for the main index page using YAML frontmatter.

```markdown
---
name: My Project
text: The fastest way to ship docs
tagline: Zero config, dark mode, Mermaid, search.
actions:
  - theme: brand
    text: Get started
    link: /getting-started/install.md
  - theme: alt
    text: GitHub
    link: https://github.com/…
features:
  - title: Zero config
    details: Drop it into any folder of Markdown.
  - title: Password protected
    details: Server-side session auth, runtime password change.
---

# Welcome

Any Markdown below the frontmatter renders normally.
```

--------------------------------

### 外部链接示例

Source: https://github.com/o7z/zdoc/blob/main/docs/authoring/links-and-routes.md

外部 URL 链接写法与普通 Markdown 相同，不受 zdoc 路由规则影响。

```markdown
[Supabase](https://supabase.com)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.