mkdocs

扩展

https://python-markdown.github.io/extensions/

排除文件

https://github.com/apenwarr/mkdocs-exclude

嵌入页面

<iframe
  src="http://localhost:5001"
  width="100%"
  height="800"
  frameborder="0">
</iframe>

加密

pip install mkdocs-encryptcontent-plugin

site_name: My Docs
theme:
  name: material

plugins:
  - search
  - encryptcontent:
      title_prefix: "🔒 "
      summary: "此页面已加密"
      placeholder: "请输入密码"
      decryption_failure_message: "密码错误"
      encryption_info_message: "🔐 本页面内容已加密"

单页面加密

---
encrypt: true
password: mypassword
---

# 这是一个加密页面
只有输入正确密码才能看到

主题

mkdocs-material

python -m pip install mkdocs-material

theme:
  name: material

* 扩展

Admonitions

markdown_extensions:
  - admonition
  - pymdownx.details

文本高亮

• tab

theme:
  features:
    - content.tabs.link

使用

=== "C"

    ``` c
    #include <stdio.h>

    int main(void) {
      printf("Hello world!\n");
      return 0;
    }
    ```

=== "C++"

    ``` c++
    #include <iostream>

    int main(void) {
      std::cout << "Hello world!" << std::endl;
      return 0;
    }
    ```

插件

mkdocs-awesome-pages-plugin

每个目录下创建.pages 文件定义nav

Note

启用 awesome-pages 插件后,请确保 mkdocs.yml 文件中没有定义 nav 配置，两者同时存在可能引发冲突

plugins:
  - awesome-pages

打开新页面

[页面](地址){ target="_blank" }

<http://xxx>{target="_blank" }

markdown_extensions:
  - attr_list

grid

<div class="grid cards" markdown>

- :fontawesome-brands-html5: [__EasyBD__](https://easybd.tools.catpd.cn) excel json 互转换工具
- :fontawesome-brands-html5: [__EasyBD__](https://easybd.tools.catpd.cn) excel json 互转换工具
</div>

引用

pip install pymdown-extensions

markdown_extensions:
  - pymdownx.snippets:
      base_path:
        - docs
      check_paths: false  # 可选，根据需要启用

Note

注意使用全路径

单行包含块格式（包含多个文件）无\ 引用

--8<-- "includes/other-file.md"

\--8<--
引用内容1
引用内2
\--8<--

引用内容

--8<-- [xx.md:name]

nginx 配置

root /home/wjn/me;
index index.html;

location / {
    try_files $uri $uri/ /index.html;
}

表格内嵌图片点击放大

pip install mkdocs-glightbox

plugins:
  - glightbox

| a   | b   |
| --- | --- |
| ![img](./imgs/tool_check_sheets.png) | |

pdf

<object data="../../assets/demo.pdf" type="application/pdf" width="100%" height="800px">
  <p>
    浏览器不支持 PDF 预览，
    <a href="../assets/demo.pdf">点击下载 PDF</a>
  </p>
</object>

插件

插件	说明
mkdocs-encryptcontent-plugin	This plugin allows you to have password protected articles and pages in MKdocs.

自定义首页

theme:
  name: material
  custom_dir: overrides

overrides/home.html

{% extends "main.html" %}

{% block content %}
<div class="custom-home">

  <section class="hero">
    <h1>我的项目</h1>
    <p>这是一个完全自定义的首页。</p>

    <a href="guide/" class="md-button md-button--primary">
      开始使用
    </a>
  </section>

  <section>
    <h2>主要功能</h2>

    <div class="grid cards">
      <div class="card">
        <h3>简单</h3>
        <p>简单易用。</p>
      </div>

      <div class="card">
        <h3>快速</h3>
        <p>性能优秀。</p>
      </div>
    </div>
  </section>

</div>
{% endblock %}

docs/index.md

---
template: home.html
---

# 首页

这是首页内容。

标题增加背景

stylesheets/extra.css

/* 给 h2 标题添加背景色，区分标题和正文 */
.md-typeset h2 {
    background-color: #e3f2fd;  /* 浅蓝色背景 */
    padding: 8px 16px;          /* 内边距 */
    border-radius: 4px;         /* 圆角 */
    border-left: 4px solid #1976d2; /* 左侧蓝色竖线装饰 */
}

/* 也可以给 h3 加不同的背景 */
.md-typeset h3 {
    background-color: #f3e5f5;
    padding: 6px 12px;
    border-radius: 4px;
    border-left: 4px solid #7b1fa2;
}

extra_css:
  - stylesheets/extra.css

• 跳过自定义的页面

/* ===== 强制重置自定义主页标题样式 ===== */
.custom-home h2,
.custom-home h3 {
    background: none !important;
    background-color: transparent !important;
    padding: 0 !important;
    border-left: none !important;
    border-radius: 0 !important;
    box-shadow: none !important;
}