博客搭建¶

约 566 个字 95 行代码 2 张图片预计阅读时间 4 分钟

Abstract

记录搭建 MkDocs 的过程

参考文档：

Task

Question

~~多个 H1 的情况，渲染会出错：主要是右侧导航栏的渲染~~

预下载¶

为了成功搭建，你需要如下预备：

python 环境，并且安装好了 pip
了解基本的 git 语法（online 部署）
了解基本的 md 语法

Material¶

由于MkDocs的原版主题确实不太好看，所以这里使用了Material For MkDocs进行优化

mkdocs new     // 新建一个MkDocs

mkdocs serve   // 建立一个预览

mkdocs build   // 建立一个静态网页

Github Page 的部署¶

自动部署需要在.github\workflows中加入ci.yml文件，内容如下：

name: ci
on:
  push:
    branches:
      - master
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
      - uses: actions/cache@v3
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

功能¶

介绍

这里我选了几个自己之后应该常用的，记一下用法

选项卡¶

分组代码块¶

=== "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;
    }
    ```

CC++

#include <stdio.h>

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

#include <iostream>

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

嵌入格式¶

嵌入

Unordered ListOrdered List

* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci

1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci

box¶

From

这一部分是从xyjj 的 Page看到的

<span class="box box-blue">blue</span>
<span class="box box-green">green</span>
<span class="box box-red">red</span>
<span class="box box-yellow">yellow</span>
<span class="box box-gray">gray</span>

blue green red yellow gray

字数统计¶

直接使用了一位学长的插件

优化 vsc 中的工作流程¶

快捷键 Markdown ShortCuts 插件
自定义 Snippet

alt text

"Color Box": {
        "prefix": "box",
        "body": [
            "<span class=\"box box-${1|blue,red,green,yellow|}\">$2</span>",
            "$3",
        ],
        "description": "Inserts a colored box span"
    },
    "Prompt": {
        "prefix": "annotation",
        "body": [
            "!!! ${1|note,info,abstract,tip,success,quote,question,warning,bug,example,failure|} \"$2\"",
            "\t$3",
        ],
        "description": "Inserts an annotation"
    },

一些用法 | 测试格式¶

Code Block¶

突出显示特定行

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

```py hl_lines="2 3"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

高亮内部代码

The `#!python range()` function is used to generate a sequence of numbers.

The range() function is used to generate a sequence of numbers.

md 格式的调整¶

代码见 CSS 部分

有序列表
有序列表

无序列表

斜体

加粗

引用

链接

下面的是一些拓展的，在 markdown - extension 中可以选择加入（建议读官方文档）

:bread:
~~删除~~
==突出显示==
^^插入^^

删除

突出显示

插入

:Todo: Mermaid 序列图¶

这里发现格式并不是很好，之后有时间了再修改 Mermaid 的配置吧。而且 Mermaid 的渲染有点慢？（

https://mermaid.js.org/syntax/flowchart.html

note

flowchart LR
subgraph subgraph1
direction TB
top1[top] --> bottom1[bottom]
end
subgraph subgraph2
direction TB
top2[top] --> bottom2[bottom]
end
 Link *to* subgraph1: subgraph1 direction is maintained
        outside --> subgraph1
         subgraph2 inherits the direction of the top-level graph (LR)
        outside ---> top2
    ```

### annotation

```md
!!! 或者 ???
???+ 折叠，默认展开状态

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.

info

abstract

tip

octicons/squirrel-16

success

quote

question

warning

bug

example

failure