MkDocs使用记录¶

Reference

mkdocs-material官方文档 https://squidfunk.github.io/mkdocs-material/

MkDocs使用记录

准备阶段¶

vscode配置¶

并推荐直接使用vscode，代码和终端控制可以同步进行，不过在vscode中，需要有python环境（即拓展 Pylance 和 Python）。

先在vscode中新建一个终端 (Ctrl+Shift+`)，执行以下命令，生成python环境。

py -m venv venv
venv\Scripts\activate

执行以下命令下载mkdocs-material包

pip install mkdocs-material

pip install mkdocs-git-revision-date-localized-plugin

准备github仓库¶

首先，需要在 github 上新建一个仓库，仓库名格式为 username+.github.io，再将该仓库拷贝到本地，在本地仓库目录下新建docs文件夹和mkdocs.yml文件(也可以直接用mkdocs命令mkdocs new)。

编写网站¶

docs 文件夹中存储网站所需要的markdown文件、css文件等等，而 mkdocs.yml 则是来选择需要什么功能。

具体功能实现参考 mkdocs-material官方文档。

在编写过程中，如果需要在浏览器中预览网站，那么需要在 mkdocs.yml 中添加dev_addr的值，作为预览的地址。如果没有给dev_addr赋值，那么系统会默认为127.0.0.1:8000，由于我的8000端口是占用的，所以我将其改为了5500端口。

dev_addr: '127.0.0.1:5500'

在由venv产生的python虚拟环境中执行指令，再在浏览器中打开所设立的地址。

mkdocs serve

发布网站¶

在python环境中执行

mkdocs build
mkdocs gh-deploy

网站便成功发布在了 https://wraithlyd.github.io 上。

高级功能¶

字体设置¶

首先在 ./docs/stylesheets 目录下放入下载的字体文件，如Font1.ttf和Font2.ttf，再新建一个 extra.css，内容如下：

@font-face {
    font-family:"Font1","Font2";
    src: url('./Font1.ttf'), format('ttf') ,"./Font2.ttf",format('ttf');
}

:root {
    --md-text-font: "Font1"; 
    --md-code-font: "Font2"; 
}

在 mkdocs.yml 中添加

theme:
    font: 
        text: Font1 
        code: Font2
extra_css:
  - stylesheets/extra.css

C code in website¶

 ```c linenums="1"
 printf("%d");
 for(i=0;i<n;i++)
     flag++;
 ```

This type can let website give you the orders of line. It displays:

printf("%d");
for(i=0;i<n;i++)
    flag++;

If it doesn't content linenums="1", it displays:

printf("%d");
for(i=0;i<n;i++)
    flag++;

提示、警告栏¶

# mkdocs.yml 相关配置
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

noteabstractinfotipsuccessquestionwarningfailuredangerbugexamplequote

Note

默认note标签。

Phasellus posuere in sem ut cursus

自定义标题的note标签。

木有标题的note标签。

!!! note

    默认note标签。

!!! note "Phasellus posuere in sem ut cursus"

    自定义标题的note标签。

!!! note ""

    木有标题的note标签。

Abstract

abstract, summary, tldr.

The three are able and use the same icon.

!!! abstract

    abstract, summary, tldr.

    The three are able and use the same icon.

Info

info, todo.

The three are able and use the same icon.

!!! info

    info, todo.

    The two are able and use the same icon.

Tip

tip, hint, important.

The three are able and use the same icon.

!!! tip

    tip, hint, important.

    The three are able and use the same icon.

Success

success, check, done.

The three are able and use the same icon.

!!! success

    success, check, done.

    The three are able and use the same icon.

Question

question, help, faq.

The three are able and use the same icon.

!!! question

    question, help, faq.

    The three are able and use the same icon.

Warning

warning, caution, attention.

The three are able and use the same icon.

!!! warning

    warning, caution, attention.

    The three are able and use the same icon.

Failure

failure, fail, missing.

The three are able and use the same icon.

!!! failure

    failure, fail, missing.

    The three are able and use the same icon.

Danger

danger, error

The three are able and use the same icon.

!!! danger

    danger, error.

    The three are able and use the same icon.

Bug

This is bug's style.

!!! bug

    This is bug's style.

Example

This is example's style.

!!! example

    This is example's style.

Quote

quote, cite.

The three are able and use the same icon.

    !!! quote

        quote, cite.

        The three are able and use the same icon.

最后更新: 2023年11月15日 17:30:52
创建日期: 2023年11月15日 17:30:52