跳转至

基本markdown内容

💡 警示框

自定义标题

Phasellus posuere in sem ut cursus

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

1
2
3
4
5
!!! note "Phasellus posuere in sem ut cursus"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

嵌套

Outer Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Inner Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
!!! note "Outer Note"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

    !!! note "Inner Note"

        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
        nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
        massa, nec semper lorem quam in massa.

移除标题

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

1
2
3
4
5
!!! note ""

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

折叠块

Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

1
2
3
4
5
??? note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

在 ??? 标记后添加一个 + 号，可以使该区块默认展开：

Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

1
2
3
4
5
???+ note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

内联块

可以作为内联块显示（例如用于侧边栏），通过 inline + end 修饰符将其放置在右侧，或者仅使用 inline 修饰符将其放置在左侧：

Lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

1
2
3
4
5
6
7
!!! info inline end "Lorem ipsum"

    Lorem ipsum dolor sit amet, consectetur
    adipiscing elit. Nulla et euismod nulla.
    Curabitur feugiat, tortor non consequat
    finibus, justo purus auctor massa, nec
    semper lorem quam in massa.

Lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

1
2
3
4
5
6
7
!!! info inline "Lorem ipsum"

    Lorem ipsum dolor sit amet, consectetur
    adipiscing elit. Nulla et euismod nulla.
    Curabitur feugiat, tortor non consequat
    finibus, justo purus auctor massa, nec
    semper lorem quam in massa.




重要提示

使用内联修饰符的警告框必须在你希望其并排显示的内容块之前声明。如果旁边空间不足以显示警告框，警告框会自动扩展至视口的整个宽度，例如在移动端视口下。

支持的类型

note

Note

这是一段用于排版的占位符文本，旨在展示页面的字体和布局效果。

abstract

Abstract

这是一段用于排版的占位符文本，旨在展示页面的字体和布局效果。

info

Info

这是一段用于排版的占位符文本，旨在展示页面的字体和布局效果。

tip

Tip

这是一段用于排版的占位符文本，旨在展示页面的字体和布局效果。

success

Success

这是一段用于排版的占位符文本，旨在展示页面的字体和布局效果。

question

Question

这是一段用于排版的占位符文本，旨在展示页面的字体和布局效果。

warning

Warning

这是一段用于排版的占位符文本，旨在展示页面的字体和布局效果。

failure

Failure

这是一段用于排版的占位符文本，旨在展示页面的字体和布局效果。

danger

Danger

这是一段用于排版的占位符文本，旨在展示页面的字体和布局效果。

bug

Bug

这是一段用于排版的占位符文本，旨在展示页面的字体和布局效果。

example

Example

这是一段用于排版的占位符文本，旨在展示页面的字体和布局效果。

quote

Quote

这是一段用于排版的占位符文本，旨在展示页面的字体和布局效果。

🗂️ 内容选项卡

将同类型但不同变体的内容组织在可切换的选项卡中，常用于多语言代码示例。

1
2
3
4
5
public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

1
print("Hello, World!")

1
console.log("Hello, World!");

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
=== "Java"

    ```java
    public class Hello {
        public static void main(String[] args) {
            System.out.println("Hello, World!");
        }
    }
    ```

=== "Python"

    ```python
    print("Hello, World!")
    ```

选项卡内可包含任意 Markdown 内容，不仅限于代码块：

  • Spring Boot
  • Spring Security
  • Spring Cloud
  1. 安装依赖
  2. 编写配置
  3. 启动应用
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
=== "无序列表"

    - Spring Boot
    - Spring Security
    - Spring Cloud

=== "有序列表"

    1. 安装依赖
    2. 编写配置
    3. 启动应用

💻 代码块增强

标题与行号

1
2
3
4
5
6
``` python title="hello.py" linenums="1"
def greet(name: str) -> str:
    return f"Hello, {name}!"

print(greet("World"))
```
hello.py
1
2
3
4
def greet(name: str) -> str:
    return f"Hello, {name}!"

print(greet("World"))

高亮指定行

1
2
3
4
5
6
7
8
``` java hl_lines="3 4"
public class Example {
    public static void main(String[] args) {
        String msg = "这两行被高亮";
        System.out.println(msg);
    }
}
```

1
2
3
4
5
6
public class Example {
    public static void main(String[] args) {
        String msg = "这两行被高亮";
        System.out.println(msg);
    }
}

代码注解

在代码中写 # (1)!，然后在代码块外按编号补充说明：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
``` yaml
server:
  port: 8080 # (1)!
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/demo # (2)!
```

1. 应用端口，默认 8080
2. 数据库连接地址，根据实际环境修改

1
2
3
4
5
server:
  port: 8080 # (1)!
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/demo # (2)!
  1. 应用端口，默认 8080
  2. 数据库连接地址，根据实际环境修改

行内语法高亮

在行内代码中使用 #!语言 前缀实现高亮：

1
2
调用 `#!python range(10)` 会生成 0 到 9 的整数序列。
Spring 注解 `#!java @RestController` 用于声明 REST 控制器。

调用 range(10) 会生成 0 到 9 的整数序列。 Spring 注解 @RestController 用于声明 REST 控制器。

复制与选择按钮

1
2
3
4
5
6
7
8
9
``` { .yaml .copy }
# 此代码块强制显示复制按钮
key: value
```

``` { .yaml .no-copy }
# 此代码块隐藏复制按钮（密码等敏感信息）
password: secret
```

✏️ 文本格式化扩展

效果 语法 示例
高亮 ==文本== 这是 高亮内容
下划线 ^^文本^^ 这是 下划线内容
删除线 ~~文本~~ 这是 删除的内容
H2O 下标 H~2~O 水的化学式：H2O
E=mc2 上标 mc^2^ 质能方程：E=mc2
++键位++ ++ctrl+s++ 保存快捷键：Ctrl+S 
1
2
3
4
5
6
这是 ==高亮内容==
这是 ^^下划线内容^^
这是 ~~删除的内容~~
水的化学式：H~2~O
质能方程：E=mc^2^
保存快捷键：++ctrl+s++

😀 图标与 Emoji

使用短码（shortcode）插入图标，各图标集用 - 分隔命名空间：

😄 ❤ 👍

1
2
3
4
:smile:
:fontawesome-brands-github:
:lucide-check:
:material-language-java:

为图标添加 tooltip 或自定义样式：

1
2
:material-information-outline:{ title="这是一条重要说明" }
:fontawesome-brands-youtube:{ .youtube }

🖼️ 图片增强

带图注（项目统一格式）


图 3.3 授权服务器的审批页面，用于处理我们客户端的请求
1
2
3
4
<figure markdown="span">
  ![](https://cdn.jsdelivr.net/gh/luguosong/images@master/blog-img/图片文件名.png){ loading=lazy }
  <figcaption>图 X.X 图注说明文字</figcaption>
</figure>

对齐

1
2
![Spring Logo](https://spring.io/img/spring.svg){ align=left width="80" }
左对齐图片，文字会在图片右侧环绕。

深色/浅色模式不同图片

1
2
![浅色模式下的图片](logo-light.png#only-light)
![深色模式下的图片](logo-dark.png#only-dark)

懒加载（无图注的简单图片）

1
![描述文字](https://example.com/image.png){ loading=lazy }

图片缩放与画廊（GLightbox）

📦 0.0.35 新增

当你需要为图片添加点击放大、画廊浏览等交互效果时，可以启用 glightbox 扩展。在 zensical.toml 中添加以下配置即可：

1
[project.markdown_extensions.zensical.extensions.glightbox]

启用后，文档中的图片会自动获得缩放和画廊功能——点击图片可放大查看，同一页面内的多张图片可通过左右箭头切换浏览。

🔲 网格布局

使用 grid cards 创建卡片式布局，适合首页或模块索引：

  • Java 基础

    面向对象、集合框架、并发编程

  • React

    组件化开发、Hooks、状态管理

  • Spring Security

    认证、授权、OAuth2

  • 数据库

    MySQL、Redis、JPA

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<div class="grid cards" markdown>

- :fontawesome-brands-java: **Java 基础**

    面向对象、集合框架、并发编程

- :fontawesome-brands-react: **React**

    组件化开发、Hooks、状态管理

</div>

📝 脚注

在正文中引用脚注1，脚注内容会自动渲染到页面底部2。

1
2
3
4
5
6
7
8
正文中的脚注引用[^1]。

[^1]: 脚注内容（单行）。

[^2]:
    多行脚注第一段。

    第二段继续缩进 4 空格。

📖 定义列表

适合用于术语解释或 API 参数说明：

Spring Boot
一个用于快速构建 Spring 应用的框架，内嵌 Tomcat，无需部署 WAR 包。
Spring Security
为 Spring 应用提供认证（Authentication）和授权（Authorization）的安全框架。
OAuth2
开放授权协议，允许第三方应用在用户授权下访问其资源，而无需获取密码。
1
2
3
4
5
`Spring Boot`
:   一个用于快速构建 Spring 应用的框架。

`Spring Security`
:   为 Spring 应用提供认证和授权的安全框架。

✅ 任务列表

  • 安装 Python 环境
  • 安装 zensical：pip install zensical
  • 运行本地预览：zensical serve
  • 编写文档内容
  • 配置导航（zensical.toml）
  • 部署到 GitHub Pages
1
2
3
- [x] 已完成的任务
- [ ] 待完成的任务
    * 子任务支持嵌套

📊 Mermaid 图表

流程图

graph LR
  A[客户端请求] --> B{是否已认证?};
  B -->|是| C[访问资源];
  B -->|否| D[跳转登录页];
  D --> E[用户登录] --> B;
1
2
3
4
5
6
7
```mermaid
graph LR
  A[客户端请求] --> B{是否已认证?};
  B -->|是| C[访问资源];
  B -->|否| D[跳转登录页];
  D --> E[用户登录] --> B;
```

时序图

sequenceDiagram
  participant 客户端
  participant 授权服务器
  participant 资源服务器
  客户端->>授权服务器: 请求授权码
  授权服务器-->>客户端: 返回授权码
  客户端->>授权服务器: 用授权码换取 Token
  授权服务器-->>客户端: 返回 Access Token
  客户端->>资源服务器: 携带 Token 请求资源
  资源服务器-->>客户端: 返回受保护资源
1
2
3
4
5
6
7
```mermaid
sequenceDiagram
  participant 客户端
  participant 授权服务器
  客户端->>授权服务器: 请求授权码
  授权服务器-->>客户端: 返回授权码
```

类图

classDiagram
  class UserDetails {
    +getUsername() String
    +getPassword() String
    +getAuthorities() Collection
  }
  class User {
    -String username
    -String password
  }
  UserDetails <|-- User

🔤 缩略词（Abbreviations）

定义缩略词后，页面中所有匹配的词汇会自动添加 tooltip 说明：

在本页中，JWT 是常见的认证令牌格式，HTML 是超文本标记语言。

1
2
3
4
JWT 是常见的认证令牌格式，HTML 是超文本标记语言。

*[JWT]: JSON Web Token
*[HTML]: HyperText Markup Language

📄 Front Matter

在文件顶部使用 YAML front matter 配置页面元数据：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
---
title: 自定义页面标题（覆盖 H1 标题）
description: 用于 SEO 的页面描述
status: new
hide:
  - navigation
  - toc
---

# 页面内容...

status 可用值（需在 zensical.toml 的 extra.status 中定义）：

值 含义
new 新增内容
deprecated 已废弃

icon 图标短码：使用 lucide/名称、fontawesome/brands/名称 等格式。

hide 可隐藏的元素：navigation（左侧导航栏）、toc（右侧目录）。

zensical.toml 配置可读性提升

配置解析器已更新至 TOML v1.1.0（0.0.34 新增），支持内联表格中的换行。这意味着 zensical.toml 中的复杂配置项（如 nav 数组中的长条目）可以跨行书写，不再必须挤在一行中。

🔘 按钮

将链接渲染为按钮样式，常用于页面底部的 CTA（行动号召）：

快速开始 立即下载 查看源码 

1
2
3
[快速开始](#){ .md-button }
[立即下载](#){ .md-button .md-button--primary }
[查看源码 :fontawesome-brands-github:](#){ .md-button }

💬 Tooltips（悬停提示）

为链接、图标添加悬停提示文字：

悬停查看提示

1
2
3
[悬停查看提示](https://spring.io "Spring 官网")

:material-information-outline:{ title="注意：此处有重要说明" }

🔗 页面间链接

推荐使用相对路径链接到 Markdown 文件

Zensical 会自动将 Markdown 文件链接转换为正确的 HTML 链接。

1
2
3
4
5
<!-- 推荐：链接到 .md 文件 -->
参考 [数学公式](../math/index.md) 章节。

<!-- 不推荐：直接链接到 HTML（部署路径变更后会失效） -->
参考 [数学公式](../math/) 章节。

链接与脚注验证

📦 0.0.38 新增

当你的文档站点规模逐渐变大，内部链接和脚注引用难免会出现失效或遗漏。手动逐一排查既耗时又容易遗漏。Zensical 现在内置了构建时验证功能，自动检查所有内部引用并报告问题，包含精确的源码位置信息。

与 MkDocs 仅验证最终渲染链接不同，Zensical 的验证覆盖范围更广——还会检查未解析的引用、未使用的定义和被遮蔽的定义。以下检查项均默认启用：

检查项 说明
unresolved_references 引用了不存在的链接目标
unresolved_footnotes 引用了未定义的脚注
unused_definitions 定义了但从未被引用的链接
unused_footnotes 定义了但从未被引用的脚注
shadowed_definitions 链接定义被后续同名定义覆盖
shadowed_footnotes 脚注定义被后续同名定义覆盖
invalid_links 链接指向了不存在的页面
invalid_link_anchors 链接锚点指向了页面中不存在的标题

在 CI 流水线中，可以配合 --strict 标志强制链接完整性——任何验证检查触发时都会使构建失败：

1
zensical build --strict

如需禁用验证，可在 zensical.toml 中设置：

1
2
[project]
validation = false

🎨 可安装的主题扩展

📦 0.0.37 新增

当你需要将项目中的主题覆盖（overrides/ 目录中的模板、样式等）打包为可复用的主题包时，可以使用可安装主题扩展（installable themes）。将主题文件打包后通过 pip 安装，只需在 mkdocs.themes 入口点注册即可被 Zensical 识别。这样就能在多个项目间共享同一套主题定制，而不需要每次都复制 overrides/ 目录。

🧩 Macros 插件

📦 0.0.40 新增

当你需要在多篇文档之间复用相同的变量值（如版本号、项目名称）或执行简单的计算逻辑时，反复手动维护既容易出错又难以保持同步。Macros 插件解决了这个问题——它覆盖了 mkdocs-macros-plugin 的功能，允许你在 Markdown 文件中定义自定义变量和函数，实现文档内容的动态生成与统一管理。

作为 Python Markdown 扩展实现，macros 也可以在 Python docstrings 中与 mkdocstrings 配合使用。

链接验证兼容

如果你同时启用了链接验证（0.0.38 新增），宏块（macros blocks）中的内容会自动从验证中排除，不会产生误报。

  1. 这是一条简短的脚注。 ↩

  2. 这是一条多行脚注。

    可以包含多段内容，使用 4 个空格缩进续行。 ↩