Nobody の 博客

Appearance

MkDocs 框架 ​

介绍 ​

MkDocs：文档、笔记、博客框架。

参考资料 ​

使用 ​

快速搭建 ​

bash
# 创建、激活虚拟环境
conda create -n mkdocs python=3.11
conda activate mkdocs

# 安装主题
pip install mkdocs-material

mkdir mkdocs-demo && cd $_

mkdocs new .      # 创建 mkdocs 项目
mkdocs serve      # 预览
mkdocs build      # 构建
mkdocs gh-deploy  # 部署
  • 目录结构
text
 ├── docs/       # 存放文档源码
 │     └── index.md
 └── mkdocs.yml  # 配置文件

部署 ​

Publishing your site - Material for MkDocs

  • 手动：mkdocs gh-deploy --force

  • GitHub Actions：示例如下

yaml
name: MKDocs deploy 
on:
  push:
    branches:
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
      - uses: actions/cache@v4
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install mkdocs-material 
      - run: mkdocs gh-deploy --force

插件 ​

自定义设置 ​

  • markdown_extensions 参数：可直接添加，无需额外安装相关依赖
yaml
# 参考设置
markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - toc:
      permalink: true
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      emoji_index: !!python/name:material.extensions.emoji.twemoji
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.magiclink:
      normalize_issue_symbols: true
      repo_url_shorthand: true
      user: squidfunk
      repo: mkdocs-material
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.snippets:
      auto_append:
        - includes/mkdocs.md
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
      combine_header_slug: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde
  • 导航栏
yaml
theme:
  features:
    - navigation.tabs

nav:
  - Home: 
    - index.md

  - XXX:
    - XXX/index.md
  • 页面底部显示 “上一页、下一页”
yaml
theme:
  features:
    - navigation.footer
  • 站点 icon 修改
yaml
theme:
  icon: 
    logo: material/notebook-outline
yaml
# reference: https://github.com/HobbitQia/notebook/blob/note1/mkdocs.yml
theme:
  palette:  # 切换昼夜模式的颜色，审美差就用默认，专业点就自定义
    - media: "(prefers-color-scheme: light)" 
      scheme: default  #配色方案：浅色模式
      # primary: brown  # 原色，默认蓝，用于标题、侧边栏、文本链接和其他几个组件
      # accent: brown  # 强调色，默认蓝，可以交互的元素如悬停链接、按钮和滚动条
      toggle:
        icon: material/weather-sunny #图标，太阳
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"  
      scheme: slate  # 配色方案：深色模式
      # primary: Brown  # 原色，默认蓝，用于标题、侧边栏、文本链接和其他几个组件
      toggle:
        icon: material/weather-night  # 图标，月亮
        name: Switch to light mode
  • custom_dir 参数：指定自定义模板和静态文件的目录路径
yaml
theme:
  custom_dir: overrides
  • 不同代码块的互相切换
text
=== "Python"

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

=== "JavaScript"

    ```javascript
    console.log("Hello, JavaScript!");
    ```
  • 添加 social link
yaml
extra:
  social:
    - name: GitHub
      icon: fontawesome/brands/github
      link: https://github.com/Bit-Part-Young
    - name: Home
      icon: fontawesome/solid/house-chimney
      link: https://seekanotherland.xyz/mkdocs-demo/

To do ​

问题 ​

  • [x] MkDocs 中的 md 文档只能有一个一级标题，hexo 可以多个（正常的 md 文档结构应是一个一级标题）
  • [x] 任务列表渲染成了圆圈样式（mkdocs 特殊方式）
  • [x] MKDocs 中连续两行都是分割线，其中的一行分割线会被当作某级标题（为兼容所有博客框架，只添加一行分割线）

版权所有 © 2024-2024 Nobody