Zensical-Flavored Markdown¶

Zensical 的 markdown 语法，备忘

提示框 Admonitions / Call-out¶

基本用法¶

!!! note
    这是一个 **note** 类型的Call-out

!!! warning
    这是一个 **warning** 类型的Call-out

进阶用法¶

自定义标题¶

!!! tip "小技巧"
    使用 `zensical serve` 实时预览文档变更

可折叠区块¶

通过 ??? 替代 !!! ，创建可折叠区块

??? example "点击展开查看更多信息"
    （ᗜ ‸ ᗜ）
    默认隐藏

???+ abstract "点击展开查看更多信息"
    （ᗜ ‸ ᗜ）
    默认展开

内联侧边栏 Inline Admonotions¶

将提示框置于段落右侧 / 左侧

!!! note inline "板鸭"
    （ᗜ ‸ ᗜ）
!!! note inline end "板鸭"
    （ᗜ ‸ ᗜ）

使用了 inline 但不想嵌入的话，可使用清除浮动的 HTML 强制指令<div style="clear: both;"></div>将后续内容隔开

Zensical 支持的类型¶

自定义图标：在 zensical.toml 中替换任意类型的图标（支持 Lucide、FontAwesome、Octicons……）

代码块 Code Blocks¶

Zensical 使用 Pygments 实现构建时语法高亮，且支持 行号、高亮、注解、复制按钮 等功能

基础语法¶

```python title="hello.py"
def greet(name):
    print(f"Hello, {name}!")
```

````markdown
```python title="hello.py"
def greet(name):
    print(f"Hello, {name}!")
```
````

外层代码块的反引号数量，必须比内层的多
title= 不能有空格

def greet(name):
print(f"Hello, {name}!")

进阶语法¶

高亮特定行¶

```C hl_lines="3" title="高亮第3行"
#include <stdio.h>
int main{
    printf("hello world!\n");
} 
```

#include <stdio.h>
int main{
    printf("hello world!\n");
} 

代码注释 Code Annotations¶

在代码注释后添加 (1)!，并在下方写注解内容

```python title="Code Blocks"
def greet(name):
    printf(f"hello,{name}!") # (1)!

greet("python")
```

1. 代码注解：为代码行添加注释说明

注意这里代码注解要再空一行

def greet(name):
    printf(f"hello,{name}!") # (1)!

greet("python")

1. 代码注解：为代码行添加注释说明（ᗜ ‸ ᗜ）

注解支持任意markdown内容，如 **加粗**、链接、:motorcycle: 表情

行内代码高亮¶

Zensical 支持行内高亮：`#!python print(" (ᗜ ˰ ᗜ) ")`

行号显示¶

加上 linenums="1" 即可

```python title="hello.py" linenums="1"
def greet(name):
    print(f"Hello, {name}!")
```

1
2

def greet(name):
    print(f"Hello, {name}!")

相关配置项¶

内容标签页 Content Tabs¶

将 不同语言、平台、配置方案 分组显示

分组代码块¶

=== "Python"
    ```python
    print("hello from python")
    ```

=== "Rust"
    ```rs
    println!("hello from rust")
    ```

print("hello from python")

println!("hello from rust")

当标签页仅包含单个代码块时，Zensical 会自动去除内边距，使外观更紧凑。

嵌套内容¶

标签页可嵌套列表、表格或更多标签页

=== "特性"
    - 支持 Mermaid
    - 内置数学公式
    - 响应式设计
=== "兼容性"
    1. 兼容 Mkdocs
    2. 支持 Instant Navigation

=== "SYS"
    === "1"
    === "2"
    === "3"

跨页联动 Linked Tabs¶

在 Zensical.toml 中启用 content.tabs.link 后，点击任意页面的 “SYS” 标签，全站所有同名标签页（如果有的话）自动切换。

卡片布局¶

<div class="grid cards" markdown>

- :fontawesome-brands-html5: __HTML__ for content and structure
- :fontawesome-brands-js: __JavaScript__ for interactivity
- :fontawesome-brands-css3: __CSS__ for text running out of boxes
- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?

</div>

<div class="grid cards" markdown>

-   :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__

    ---

    Install [`zensical`](#) with [`pip`](#) and get up
    and running in minutes

    [:octicons-arrow-right-24: Getting started](#)

-   :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__

    ---

    Focus on your content and generate a responsive and searchable static site

    [:octicons-arrow-right-24: Reference](#)

-   :material-format-font:{ .lg .middle } __Made to measure__

    ---

    Change the colors, fonts, language, icons, logo and more with a few lines

    [:octicons-arrow-right-24: Customization](#)

-   :material-scale-balance:{ .lg .middle } __Open Source, MIT__

    ---

    Zensical is licensed under MIT and available on [GitHub](https://github.com/zensical/zensical)

    [:octicons-arrow-right-24: License](#)

</div>

空行是必要的！

图表 Diagrams¶

通过 Mermaid.js,用纯文本绘制图表。

支持的图表类型¶

• 流程图 （Flowchart）
• 时序图 （Sequence Diagram）
• 状态图 （State Diagram）
• 类图 （Class Diagram）
• 实体关系图 （ER Diagram）

自动适配深色/浅色主题，且与 Instant Navigation 兼容

```mermaid
graph TD  # 上下
    A[开始] --> B(处理);
    B --> C{条件?};
    C -- 是 --> D[操作1];
    C -- 否 --> E[操作2];
    D --> F[结束];
    E --> F;
```

```mermaid
graph LR  #左右
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];
```

graph TD
    A[开始] --> B(处理);
    B --> C{条件?};
    C -- 是 --> D[操作1];
    C -- 否 --> E[操作2];
    D --> F[结束];
    E --> F;

graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];

Mermaid 语法¶

详见 Mermaid 语法

脚注 Footnotes¶

为特定词句添加补充说明，不打断阅读流

这是一句带有脚注的句子[^1]

将鼠标悬停于其上即可看到提示

[^1]: 这是脚注内容

这是一句带有脚注的句子¹

将鼠标悬停于其上即可看到提示

启用悬浮提示¶

在配置中开启 content.footnote.tooltips，脚注将变为内联悬浮提示

文本格式 Formatting¶

更丰富的排版

- ==高亮==             → <mark>
- ^^下划线^^           → <ins>
- ~~删除线~~           → <del>
- H~2~O              → H<sub>2</sub>O  H₂O（下标）
- A^T^A              → A<sup>T</sup>A  AᵀA（上标）
- ++ctrl+alt+del++     → 键盘按键样式

• 高亮
• 下划线
• 删除线
• H₂O
• A^TA
• Ctrl+Alt+Del

需启用 pymdownx.caret, pymdownx.mark, pymdownx.tilde, pymdownx.keys

图标 & 表情符号 Icons & Emojis¶

Zensical 内置 10,000+ 图标（Lucide、FontAwesome、Material Icons、Octicons、Simple Icons）和数千个 Emoji

使用方式¶

图标：
* :sparkles: `:sparkles:`
* :fontawesome-brands-python: `:fontawesome-brands-python:`
* :lucide-git-pull-request: `:lucide-git-pull-request:`
表情：
* :rocket: `:rocket:`
* :tada: `:tada:`
* :memo: `:memo:`
* :eyes: `:eyes:`

图标：

• :sparkles:
• :fontawesome-brands-python:
• :lucide-git-pull-request:

表情：

• :rocket:
• :tada:
• :memo:
• :eyes:

Zensical 内置的图标集¶

以下图标集随 Zensical 一起打包提供（链接指向各图标集的搜索页面）：

• Lucide
• Material Design
• FontAwesome
• Octicons
• Simple Icons

自定义样式¶

通过 Attribute Lists 添加 CSS 类

:fontawesome-brands-github:{ .github-icon }

图片¶

基本语法¶

![绀海](../images/ganhai.jpg)

控制大小 + 对齐¶

# 限制宽度为 400px，并且让文字在图片右侧环绕 (靠左对齐)
![avatar](../images/avatar.jpg){ width="400" align=left }

# 限制宽度的同时开启懒加载（长文必备，性能拉满）
![Nexys A7 开发板实拍](../assets/fpga_board.jpg){ width="80%" loading=lazy }

数学公式 Maths¶

支持 KaTeX（轻量快速） 或 MathJax（功能全面）

行内公式¶

质能方程：$E = mc^2$

欧拉公式：$e^{ix} = cos x + isin x$

\(E = mc^2\)

\(e^{ix} = cosx + isinx\)

块级公式¶

$$
\cos x = \sum_{k=0}^{infty} \frac{(-1)^k}{(2k)!} x^{2k}
$$

任务列表 Task Lists¶

- [x] 安装 Zensical
- [x] 配置 `zensical.toml`
- [ ] 部署到平台
- [x] 编写文档

• 安装 Zensical
• 配置 zensical.toml
• 部署到平台
• 编写文档

需启用 pymdownx.tasklist

设置 custom_checkbox = true 以使用自定义样式

工具提示 Tooltips¶

为链接或图标添加悬浮说明

链接提示¶

[将鼠标悬停在此处][example]
[example]: http://example.com "我是一个工具提示♪(^∇^*)"

缩写词提示¶

定义缩写词：

*[API]: Application Programming Interface
*[CLI]: Command-Line Interface

当文中出现 API 时，自动显示提示，如 API、CLI

启用 content.tooltips 时，提示样式更加美观

参考文档¶

• Zensical 官方文档 - Authoring
• 在 Zensical 中高效写作：Markdown 高级语法指南