### Quick Start

Source: https://github.com/rainppr/mkpandocs/blob/master/README.md

Install mkpandocs, install dependencies, create a new project, and serve it.

```bash
pip install mkpandocs
mkpandocs install-deps
mkpandocs new my-docs
cd my-docs
mkpandocs serve
```

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

### Development Environment Setup

Source: https://github.com/rainppr/mkpandocs/blob/master/README.md

Clone the repository, navigate to the directory, install development dependencies, and install mkpandocs dependencies.

```bash
git clone https://github.com/RainPPR/mkpandocs.git
cd mkpandocs
uv sync --group dev
uv run mkpandocs install-deps
```

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

### Serve Command Examples

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/cli.md

Examples of using the 'mkpandocs serve' command.

```bash
# 指定端口
mkpandocs serve --dev-addr 0.0.0.0:8080

# 脏模式
mkpandocs serve --dirtyreload
```

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

### Build Command Examples

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/cli.md

Examples of using the 'mkpandocs build' command.

```bash
# 指定输出目录
mkpandocs build --site-dir public

# 严格模式
mkpandocs build --strict
```

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

### Start Development Server

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/cli.md

Command to start the development server with automatic reload support.

```bash
mkpandocs serve [选项]
```

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

### Install Pandoc Dependencies

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/cli.md

Command to install necessary Pandoc dependencies.

```bash
mkpandocs install-deps
```

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

### Example 1: Regular Highlighted Admonition Block

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/example-filters.md

Example of a 'warning' type admonition block used for drawing reader attention or making special notes.

```markdown
```md {admonition="warning" title="注意：请勿除以 $0$"}
在进行上述计算时，请确保分母 **绝对不为零**，否则会引发 `ZeroDivisionError`。
```
```

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

### Get Required Dependencies

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/cli.md

Command to display the required Pandoc dependencies.

```bash
mkpandocs get-deps
```

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

### Example 2: Details Foldable Block

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/example-filters.md

Example of a 'details' type admonition block, which renders as a collapsible section, useful for longer or supplementary content.

```markdown
```md {admonition="details" title="点击查看 $E=mc^2$ 的详细推导过程"}
根据相对论，我们可以推导出：

1. 质量和能量是等价的
2. 具体的推导公式如下...
```
```

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

### on_config 事件处理函数

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/plugins.md

插件中 on_config 事件处理函数的示例。

```python
def on_config(self, config, **kwargs):
    # 可以修改配置
    return config
```

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

### 构建静态站点

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/getting-started.md

使用 mkpandocs build 命令构建静态站点，生成的文件位于 site/ 目录。

```bash
mkpandocs build
```

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

### draft_docs

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

标记为草稿的文件，在 serve 时可用但不会包含在构建中。

```yaml
draft_docs: |
  drafts/
  *_draft.md
```

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

### plugins

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

启用的插件列表。

```yaml
plugins:
  - search
  - autorefs
```

```yaml
plugins: []
```

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

### 创建新项目

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/getting-started.md

使用 mkpandocs new 命令创建一个新的文档项目。

```bash
mkpandocs new my-docs
cd my-docs
```

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

### 本地预览

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/getting-started.md

使用 mkpandocs serve 命令启动本地开发服务器，并在 http://127.0.0.1:8000 查看文档。服务器支持自动重载。

```bash
mkpandocs serve
```

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

### Build Static Site

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/cli.md

Command to build the static site into the 'site/' directory.

```bash
mkpandocs build [选项]
```

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

### docs_dir

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

文档源文件目录。

```yaml
docs_dir: docs
```

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

### watch

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

serve 时额外监视的目录。

```yaml
watch:
  - properdocs
```

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

### on_nav 事件处理函数

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/plugins.md

插件中 on_nav 事件处理函数的示例。

```python
def on_nav(self, nav, config, files, **kwargs):
    # 可以修改导航结构
    return nav
```

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

### 基本插件结构

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/plugins.md

开发一个继承自 properdocs.plugins.BasePlugin 的插件的基本 Python 类结构。

```python
from properdocs.plugins import BasePlugin
from properdocs.config import config_options as c


class MyPluginConfig(properdocs.config.base.Config):
    my_option = c.Type(str, default='default_value')


class MyPlugin(BasePlugin[MyPluginConfig]):
    def on_page_markdown(self, markdown, page, config, files, **kwargs):
        # 在 Markdown 渲染前处理
        return markdown

    def on_page_content(self, html, page, config, files, **kwargs):
        # 在 HTML 渲染后处理
        return html
```

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

### 配置系统 - SubConfig 嵌套

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/architecture.md

使用 SubConfig 实现嵌套配置的 Python 代码示例。

```python
class PandocConfig(base.Config):
    format = c.Type(str, default='markdown')
    to = c.Type(str, default='html5')

class ProperDocsConfig(base.Config):
    pandoc = c.SubConfig(PandocConfig)
```

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

### on_post_build 事件处理函数

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/plugins.md

插件中 on_post_build 事件处理函数的示例。

```python
def on_post_build(self, config, **kwargs):
    # 执行构建后操作
    pass
```

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

### 发布插件的 entry_points 配置

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/plugins.md

在 pyproject.toml 中使用 entry_points 注册插件的示例。

```toml
[project.entry-points."properdocs.plugins"]
my-plugin = "my_package.plugin:MyPlugin"
```

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

### pandoc.to

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

Pandoc 的输出格式。

```yaml
pandoc:
  to: html5
```

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

### pandoc.args

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

传递给 Pandoc 的额外参数。

```yaml
pandoc:
  args:
    - --wrap=none
    - --number-sections
```

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

### Create New Project

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/cli.md

Command to create a new MkPandocs documentation project in a specified or current directory.

```bash
mkpandocs new [目录名]
```

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

### Deploy to GitHub Pages

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/cli.md

Command to deploy the documentation site to GitHub Pages.

```bash
mkpandocs gh-deploy [选项]
```

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

### site_description

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

站点描述，会添加到 HTML 的 meta 标签中。

```yaml
site_description: 我的项目文档
```

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

### site_dir

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

构建输出目录。

```yaml
site_dir: site
```

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

### 环境变量

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

可以使用 !ENV 标签从环境变量读取配置值。

```yaml
site_name: !ENV SITE_NAME
```

```yaml
site_name: !ENV [SITE_NAME, '默认站点名称']
```

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

### 编写第一篇文档

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/getting-started.md

编辑 docs/index.md 文件来编写你的第一篇文档，支持 Markdown、LaTeX 和代码高亮。

```markdown
# 我的项目文档

欢迎使用我的项目。

## 功能特性

- 支持 Pandoc 渲染
- 支持 LaTeX 数学公式：$E = mc^2$
- 支持代码高亮
```

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

### nav

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

定义站点导航结构。路径相对于 docs_dir。

```yaml
nav:
  - 首页: index.md
  - 指南:
    - 快速开始: guide/getting-started.md
    - 配置: guide/configuration.md
  - API: api/reference.md
```

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

### 使用 pip 安装 MkPandocs

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/getting-started.md

使用 pip 包管理器安装 MkPandocs 及其 Pandoc 依赖。

```bash
pip install mkpandocs
mkpandocs install-deps
```

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

### 项目结构

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/architecture.md

MkPandocs 的项目结构概览。

```tree
mkpandocs/
├── properdocs/              # 核心包
│   ├── __main__.py         # CLI 入口
│   ├── commands/           # 命令实现
│   │   ├── build.py        # 构建命令
│   │   ├── serve.py        # 服务命令
│   │   ├── new.py          # 创建项目
│   │   └── gh_deploy.py    # GitHub Pages 部署
│   ├── config/             # 配置系统
│   │   ├── defaults.py     # 配置定义（ProperDocsConfig）
│   │   ├── config_options.py # 配置选项类型
│   │   └── base.py         # 配置基类
│   ├── structure/          # 文档结构处理
│   │   ├── pages.py        # 页面处理 + Pandoc 渲染
│   │   ├── nav.py          # 导航构建
│   │   ├── files.py        # 文件处理
│   │   └── toc.py          # 目录生成
│   ├── plugins.py          # 插件系统
│   └── theme.py            # 主题处理
├── filters/                # 示例过滤器
│   ├── link_class.lua      # Lua filter
│   └── add_target_blank.py # JSON filter
├── docs/                   # 文档源文件
├── mkpandocs.yml           # 项目配置
└── pyproject.toml          # Python 包配置
```

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

### 文件布局示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

推荐使用 index.md 作为每个目录的首页，并展示了文档源文件的目录结构。

```markdown
docs/
├── index.md
├── guide/
│   ├── getting-started.md
│   └── configuration.md
└── api/
    └── reference.md
```

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

### theme

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

设置文档主题。

```yaml
# 使用内置主题
theme: mkdocs
```

```yaml
# 使用带配置的主题
theme:
  name: material
  language: zh
  palette:
    - scheme: default
      primary: indigo
  features:
    - navigation.instant
    - search.highlight
```

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

### 使用 uv 安装 MkPandocs

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/getting-started.md

使用 uv 包管理器安装 MkPandocs 及其 Pandoc 依赖。

```bash
# 安装 uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 添加 MkPandocs 依赖
uv add mkpandocs

# 安装 Pandoc 依赖
uv run mkpandocs install-deps
```

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

### site_name

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

文档站点的标题，这是唯一的必填配置。

```yaml
site_name: 我的项目文档
```

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

### extra_css

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

额外的 CSS 文件。

```yaml
extra_css:
  - css/custom.css
```

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

### pandoc.format

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

Pandoc 的输入格式。

```yaml
pandoc:
  format: markdown+raw_html+raw_attribute
```

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

### 从源码安装 MkPandocs

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/getting-started.md

从 GitHub 克隆源码并安装 MkPandocs 及其 Pandoc 依赖。

```bash
git clone https://github.com/RainPPR/mkpandocs.git
cd mkpandocs
uv sync
uv run mkpandocs install-deps
```

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

### 部署到自托管服务器 (nginx)

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/deploying.md

将构建后的 site/ 目录内容复制到 nginx 的 web 根目录。

```bash
cp -r site/* /var/www/html/
```

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

### strict

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

严格模式，遇到警告时停止构建。

```yaml
strict: false
```

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

### 配置系统 - SubConfig 嵌套 YAML

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/architecture.md

使用 SubConfig 实现嵌套配置的 YAML 示例。

```yaml
pandoc:
  format: markdown+raw_html+raw_attribute
  to: html5
```

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

### site_url

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

站点的完整 URL，用于生成 canonical 链接。

```yaml
site_url: https://example.com/docs/
```

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

### extra

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

传递给模板的额外数据。

```yaml
extra:
  version: 1.0.0
```

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

### on_page_markdown 事件处理函数

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/plugins.md

插件中 on_page_markdown 事件处理函数的示例。

```python
def on_page_markdown(self, markdown, page, config, files, **kwargs):
    # 修改 Markdown 内容
    return markdown
```

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

### dev_addr

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

开发服务器地址。

```yaml
dev_addr: 127.0.0.1:8000
```

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

### on_files 事件处理函数

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/plugins.md

插件中 on_files 事件处理函数的示例。

```python
def on_files(self, files, config, **kwargs):
    # 可以添加或移除文件
    return files
```

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

### 完整配置示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

一个完整的 MkPandocs 配置示例。

```yaml
site_name: 我的项目文档
site_url: https://example.com/docs/
site_description: 项目文档
site_author: 开发团队

repo_url: https://github.com/user/repo
edit_uri: blob/main/docs/

theme:
  name: material
  language: zh
  palette:
    - scheme: default
      primary: indigo
      accent: indigo

nav:
  - 首页: index.md
  - 指南:
    - 入门: guide/getting-started.md
    - 配置: guide/configuration.md

pandoc:
  format: markdown+raw_html+raw_attribute
  to: html5
  args:
    - --wrap=none
  html_parser: html.parser

plugins:
  - search
  - autorefs

strict: false
use_directory_urls: true
```

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

### Markdown 表格对齐示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

展示了 Markdown 表格中列的对齐方式。

```markdown
| 左对齐 | 居中 | 右对齐 |
|:-------|:----:|-------:|
| a      |  b   |      c |
```

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

### 简易插件（hooks）实现

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/plugins.md

在 my_hooks.py 文件中直接定义事件处理函数的示例。

```python
def on_page_markdown(markdown, page, **kwargs):
    return markdown.replace('foo', 'bar')
```

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

### GitHub Actions 自动部署

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/deploying.md

使用 GitHub Actions 在每次推送到 main 分支时自动部署文档。

```yaml
name: Deploy Docs
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install mkpandocs
      - run: mkpandocs install-deps
      - run: mkpandocs build --strict
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site
```

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

### 启用插件

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/plugins.md

在 mkpandocs.yml 中启用插件的示例。

```yaml
plugins:
  - search
  - my-plugin:
      option1: value1
```

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

### 部署到自托管服务器 (Python 简单服务器)

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/deploying.md

使用 Python 的内置 http.server 模块在本地托管 site/ 目录。

```bash
cd site && python -m http.server 8080
```

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

### 启用 hooks

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/plugins.md

在 mkpandocs.yml 中使用 hooks 的示例。

```yaml
hooks:
  - my_hooks.py
```

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

### Pandoc 配置

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

所有 Pandoc 相关配置都在 pandoc 嵌套节点下。

```yaml
pandoc:
  format: markdown+raw_html+raw_attribute
  to: html5
  args: []
  filters: []
  lua_filters: []
  keep_frontmatter: false
  html_parser: html.parser
  json_filters: []
```

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

### extra_javascript

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

额外的 JavaScript 文件。

```yaml
extra_javascript:
  - js/custom.js
```

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

### pandoc.lua_filters

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

Lua 过滤器列表，路径相对于当前工作目录。

```yaml
pandoc:
  lua_filters:
    - filters/link_class.lua
```

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

### 内联 HTML 示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

展示了如何在 Markdown 中使用 HTML 的 `<details>` 和 `<summary>` 标签。

```html
<details>
<summary>点击展开</summary>
这里是隐藏的内容。
</details>
```

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

### use_directory_urls

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

是否使用目录式 URL。

```yaml
use_directory_urls: true
```

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

### 打包主题

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/themes.md

通过 `pyproject.toml` 文件中的 `[project.entry-points."properdocs.themes"]` 来将自定义主题打包为 Python 包。

```toml
# pyproject.toml
[project.entry-points."properdocs.themes"]
my-theme = "my_theme"
```

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

### on_page_context 事件处理函数

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/plugins.md

插件中 on_page_context 事件处理函数的示例。

```python
def on_page_context(self, context, page, config, nav, **kwargs):
    # 修改模板上下文
    return context
```

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

### repo_url

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

源代码仓库链接。

```yaml
repo_url: https://github.com/user/repo
```

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

### 自动部署到 GitHub Pages

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/deploying.md

使用 mkpandocs gh-deploy 命令自动将 site/ 目录推送到 gh-pages 分支。

```bash
mkpandocs gh-deploy
```

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

### Standard Syntax Format

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/example-filters.md

Demonstrates the standard syntax for admonition blocks using 'md' or 'markdown' code blocks with 'admonition' attributes.

```markdown
```md {admonition="类型" title="区块标题"}
这里是内部正文内容，支持各类 Markdown 语法。
```
```

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

### on_page_read_source 事件处理函数

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/plugins.md

插件中 on_page_read_source 事件处理函数的示例。

```python
def on_page_read_source(self, page, config, **kwargs):
    # 可以返回自定义的 Markdown 内容
    return None  # 返回 None 使用文件内容
```

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

### Markdown 强调示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

展示了 Markdown 中斜体、粗体和删除线的写法。

```markdown
*斜体* 或 _斜体_
**粗体** 或 __粗体__
~~删除线~~
```

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

### Markdown 表格示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

展示了标准 Markdown 表格的写法。

```markdown
| 列 1 | 列 2 | 列 3 |
|------|------|------|
| 数据 | 数据 | 数据 |
```

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

### Markdown 无序列表示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

展示了 Markdown 中无序列表的写法。

```markdown
- 第一项
- 第二项
- 第三项
```

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

### 自定义现有主题

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/themes.md

通过 `custom_dir` 覆盖现有主题的文件，并可以指定静态模板如 404.html。

```yaml
theme:
  name: mkdocs
  custom_dir: theme_overrides/
  static_templates:
    - 404.html
```

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

### Markdown 图片示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

展示了 Markdown 中图片的写法，包括替代文字。

```markdown
![替代文字](img/screenshot.png)
```

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

### Markdown 引用示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

展示了 Markdown 中引用块的写法，可以包含多个段落。

```markdown
> 这是一段引用文字。
>
> 引用可以包含多个段落。
```

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

### Markdown 有序列表示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

展示了 Markdown 中有序列表的写法。

```markdown
1. 第一步
2. 第二步
3. 第三步
```

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

### Markdown 转义字符示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

使用反斜杠 `\` 来转义 Markdown 的特殊字符，使其显示为普通文本。

```markdown
\* 不是斜体 \*
\$ 不是公式 \$
\# 不是标题 \#
```

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

### on_page_content 事件处理函数

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/plugins.md

插件中 on_page_content 事件处理函数的示例。

```python
def on_page_content(self, html, page, config, files, **kwargs):
    # 修改 HTML 内容
    return html
```

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

### 行内公式示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

使用 $...$ 嵌入行内 LaTeX 数学公式。

```markdown
质能方程 $E = mc^2$ 是著名的物理公式。
```

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

### pandoc.json_filters

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

JSON AST 过滤器列表。每个过滤器是一个 Python 脚本，通过 stdin 接收 Pandoc JSON AST，处理后通过 stdout 输出。详见 JSON 过滤器。

```yaml
pandoc:
  json_filters:
    - filters/add_target_blank.py
```

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

### copyright

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

版权信息，显示在页面底部。

```yaml
copyright: Copyright &copy; 2026 MyName
```

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

### 独立公式示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

使用 $$...$$ 创建独立的 LaTeX 数学公式块。

```markdown
高斯积分：

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$
```

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

### Markdown 标题示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

展示了 Markdown 中一级、二级和三级标题的写法。

```markdown
# 一级标题
## 二级标题
### 三级标题
```

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

### site_author

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

作者名称，会添加到 HTML 的 meta 标签中。

```yaml
site_author: 作者名称
```

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

### 行内代码示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

使用反引号 `code` 来表示行内代码。

```markdown
`code`
```

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

### 渲染流程 - 2. 文件收集

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/architecture.md

文件收集流程图。

```text
docs_dir → 扫描 .md 文件 → 应用 exclude_docs/draft_docs → Files 对象
```

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

### 在配置中使用自定义主题

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/themes.md

通过 `theme.name: null` 和 `theme.custom_dir` 指定自定义主题的路径。

```yaml
theme:
  name: null
  custom_dir: my_theme/
```

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

### pandoc.filters

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

Pandoc 过滤器列表（外部程序，通过 JSON 与 Pandoc 通信）。

```yaml
pandoc:
  filters:
    - pandoc-crossref
```

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

### pandoc.keep_frontmatter

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

是否保留 YAML frontmatter。设为 False 时会剥离 frontmatter（与标准 MkDocs 行为一致）。

```yaml
pandoc:
  keep_frontmatter: false
```

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

### Python 代码示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

一个简单的 Python 斐波那契数列函数示例。

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)
```

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

### exclude_docs

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

使用 .gitignore 格式的模式排除文件。

```yaml
exclude_docs: |
  *.py
  drafts/
```

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

### pandoc.html_parser

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

BeautifulSoup 使用的 HTML 解析器。

```yaml
pandoc:
  html_parser: html.parser
```

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

### 配置系统 - 访问方式

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/architecture.md

访问嵌套和扁平配置的 Python 代码示例。

```python
# 嵌套配置通过属性访问
config.pandoc.format  # 'markdown+raw_html+raw_attribute'
config.pandoc.to      # 'html5'

# 扁平配置通过 dict 访问
config.get('site_name', '')
```

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

### Jinja2 继承

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/themes.md

使用 Jinja2 的 `{% extends %}` 和 `{% block %}` 来继承和覆盖模板。

```html
{% extends "base.html" %}

{% block content %}
{{ page.content }}
{% endblock %}
```

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

### validation

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

配置链接验证的严格程度。每个值可以是 warn、info、ignore。

```yaml
validation:
  nav:
    omitted_files: info
    not_found: warn
    absolute_links: info
  links:
    not_found: warn
    anchors: info
    absolute_links: info
    unrecognized_links: info
```

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

### Markdown 链接示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

展示了 Markdown 中外部链接和内部链接的写法。

```markdown
[链接文字](https://example.com)
[内部链接](guide/getting-started.md)
```

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

### 手动部署到 GitHub Pages

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/deploying.md

手动构建站点，然后将 site/ 目录的内容推送到 gh-pages 分支。

```bash
mkpandocs build
git checkout gh-pages
cp -r site/* .
git add .
git commit -m "Update docs"
git push origin gh-pages
```

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

### 使用内置主题

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/themes.md

通过在配置中指定 `theme` 字段来选择 MkDocs 或 ReadTheDocs 主题。

```yaml
theme: mkdocs          # MkDocs 主题
theme: readthedocs     # ReadTheDocs 主题
```

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

### 渲染流程 - 1. 配置加载

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/architecture.md

配置加载流程图。

```text
mkpandocs.yml → ProperDocsConfig.load_file() → 验证 → 配置对象
```

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

### Jinja2 循环

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/themes.md

使用 Jinja2 的 `{% for %}` 标签遍历列表，例如用于渲染导航菜单项。

```html
{% for nav_item in nav %}
<li {% if nav_item.active %}class="active"{% endif %}>
    <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
</li>
{% endfor %}
```

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

### edit_uri

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/configuration.md

编辑链接的 URI 后缀。

```yaml
edit_uri: blob/main/docs/
```

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

### Markdown 分割线示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

使用三个或更多的连字符、星号或下划线来创建水平分割线。

```markdown
---

```

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

### LaTeX 求和示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

展示了 LaTeX 中求和的写法。

```latex
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
```

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

### Jinja2 条件渲染

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/themes.md

使用 Jinja2 的 `{% if %}` 标签进行条件渲染，例如仅当页面存在目录时显示目录导航。

```html
{% if page.toc %}
<nav class="toc">
    {{ page.toc }}
</nav>
{% endif %}
```

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

### LaTeX 分数示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

展示了 LaTeX 中分数的写法。

```latex
\frac{a}{b}
```

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

### JSON 过滤器管线

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/architecture.md

当 pandoc.json_filters 非空时，渲染使用的三步管线说明。

```text
1. pypandoc.convert_text(markdown, to='json', format=format) — Markdown → JSON AST
2. 对每个 filter 执行 subprocess.run([python, filter], input=json) — AST 处理
3. pypandoc.convert_text(json_data, to='html5', format='json') — JSON AST → HTML
```

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

### 围栏代码块示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/writing-your-docs.md

使用三个反引号 ``` 来创建围栏代码块，并可以指定语法高亮语言。

```markdown
```python
def hello():
    print("Hello, World!")
```
```

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

### 渲染流程 - 5. 模板渲染

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/architecture.md

模板渲染流程图。

```text
HTML 内容 + 主题模板 → Jinja2 渲染 → 最终 HTML 文件
```

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

### 渲染流程 - 3. 导航构建

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/architecture.md

导航构建流程图。

```text
nav 配置 → 匹配 Files → Navigation 对象
```

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

### Lua Function for Admonition

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/user-guide/example-filters.md

This Lua function processes Markdown code blocks to create admonition and details elements. It checks for 'md' or 'markdown' classes and extracts 'admonition' and 'title' attributes to format the output as HTML details or admonition blocks.

```lua
function CodeBlock(el)
    -- 1. 检查语言是否为 md 或 markdown
    if el.classes:includes('md') or el.classes:includes('markdown') then
        
        -- 2. 获取 admonition 属性（得益于标准的 key="value" 写法，这里现在绝对稳定）
        local admonition_type = el.attributes['admonition']
        
        if admonition_type then
            
            -- 获取 title 属性
            local title_raw = el.attributes['title']
            
            -- 【细节优化】如果是 details 且没有传 title，默认给一个 "Details"
            if admonition_type == "details" and not title_raw then
                title_raw = "Details"
            else
                title_raw = title_raw or "Admonition"
            end

            -- 3. 将 title 作为 Markdown 重新解析（支持行内公式等）
            local title_doc = pandoc.read(title_raw, "markdown")
            local title_inlines = pandoc.List()
            if #title_doc.blocks > 0 and title_doc.blocks[1].content then
                title_inlines = title_doc.blocks[1].content

                
            end

            local title_doc = pandoc.read(title_raw, "markdown")
            local title_blocks = title_doc.blocks

            -- 第二个参数 {pandoc.Space()} 是块与块之间的分隔符
            -- 它会自动遍历所有 block 并提取它们的 inline 内容
            local title_inlines = pandoc.utils.blocks_to_inlines(title_blocks, {pandoc.Space()})

            -- 4. 将代码块内的文本同样作为 Markdown 重新解析
            local content_doc = pandoc.read(el.text, "markdown")
            local content_blocks = content_doc.blocks

            -- ==========================================
            -- 分支 A：处理 admonition="details" (折叠块)
            -- ==========================================
            if admonition_type == "details" then
                
                -- 构造 <summary>...</summary> 的行内元素
                local summary_inlines = pandoc.List()
                summary_inlines:insert(pandoc.RawInline("html", "<summary>"))
                summary_inlines:extend(title_inlines)
                summary_inlines:insert(pandoc.RawInline("html", "</summary>"))
                
                -- 放入纯文本段落中，防止被包进多余的 <p>
                local summary_p = pandoc.Plain(summary_inlines)

                -- 组装默认收缩的 <details> 区块
                local final_blocks = pandoc.List()
                final_blocks:insert(pandoc.RawBlock('html', '<details>'))
                final_blocks:insert(summary_p)
                final_blocks:extend(content_blocks)
                final_blocks:insert(pandoc.RawBlock('html', '</details>'))

                -- 返回包裹好的 Div
                return pandoc.Div(final_blocks, pandoc.Attr("", {"details-wrapper"}))

            -- ==========================================
            -- 分支 B：处理常规 admonition (note, warning 等)
            -- ==========================================
            else
                -- 构造 <p class="admonition-title">...</p>
                local p_start = pandoc.RawInline("html", '<p class="admonition-title">')
                local p_end   = pandoc.RawInline("html", '</p>')
                
                local p_content = pandoc.List({p_start})
                p_content:extend(title_inlines)
                p_content:insert(p_end)

                -- 必须使用 Plain (纯文本块)
                local title_p = pandoc.Plain(p_content)

                -- 组装 admonition 区块
                local final_blocks = pandoc.List({title_p})
                final_blocks:extend(content_blocks)

                -- 返回 <div class="admonition {type}">...</div>
                return pandoc.Div(final_blocks, pandoc.Attr("", {"admonition", admonition_type}))
            end
        end
    end
    
    -- 如果不是目标代码块，原样返回
    return nil
end
```

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

### 渲染流程 - 4. 页面渲染

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/architecture.md

页面渲染流程图。

```text
read_source() → Markdown 内容 + 元数据
    ↓
render() → Pandoc 处理
    ↓
    ├── 无 json_filters: markdown → html5
    └── 有 json_filters: markdown → json → filter chain → html5
    ↓
_PandocHTMLParser.process() → 提取锚点/标题、重写链接
    ↓
HTML 内容 + TOC
```

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

### 自定义主题基本结构

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/themes.md

自定义主题的基本文件结构，包括主模板、导航模板、基础模板和样式文件。

```tree
my_theme/
├── main.html          # 主模板
├── nav.html           # 导航模板
├── base.html          # 基础模板
└── css/
    └── theme.css      # 样式文件
```

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

### 主模板示例

Source: https://github.com/rainppr/mkpandocs/blob/master/docs/dev-guide/themes.md

一个基本的主模板示例，展示了如何使用 Jinja2 变量来渲染页面标题、站点名称、导航和内容。

```html
<!DOCTYPE html>
<html>
<head>
    <title>{{ page.title }} - {{ site_name }}</title>
    <meta charset="utf-8">
    {% for css in extra_css %}
    <link href="{{ css }}" rel="stylesheet">
    {% endfor %}
</head>
<body>
    <nav>
        {% for nav_item in nav %}
        <a href="{{ nav_item.url }}"
           {% if nav_item.active %}class="active"{% endif %}>
            {{ nav_item.title }}
        </a>
        {% endfor %}
    </nav>
    <main>
        <h1>{{ page.title }}</h1>
        {{ page.content }}
    </main>
</body>
</html>
```

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