created: [ 2022-04-04 22:42 ]

aliases: [ mkdocs 笔记 ]

tags: [  vps ]

number headings: first-level 1, max 6, auto, contents toc

1 常用命令

1.1 安装

conda install -c conda-forge mkdocs

1.2 部署到所有 ip.

默认仅仅是部署到单机 ip. 如下命令修改为公网访问.

mkdocs serve –dev-addr 0.0.0.0:8000

参考链接Fetching Title#mprb

1.3 nav 参数说明

使用 nav 参数的话, 当前的版本 20220404必须指定具体文件, 没法用通配符.

故,只能删掉 nav 配置了.

1.4 使用第三方 material themes 的话,打开很卡.

1. 排除了 md 文档格式问题.

1.5 yml 配置注意点

1. 冒号后面要加空格

1.6 文章标题的规则

1. 网址是文件名

2. 先看正文第一行 若是标题格式, 就是显示的标题.

3. 若第一行不是标题的格式, 就显示的是文件名

1.7 关于 css 的配置

我这边不管是配置extra.css还是在custom_theme/css 中配置extra.css都不会生效.

唯一可以生效的办法是通过如下命令找到默认主题文件夹, 复制到站点根路径的custom_theme下面

# 找mkdocs 这个主题名字路径
mkdocs --version

然后修改对应的 base.css 文件.

最后重新 serve 才能生效.

favicon.ico 也一样修改.

1.8 关于 主题文件/extend_theme 路径问题

1.8.1 custom_dir:

mkdocs.yml 运行的环境变量是在 mkdocs 根路径. 故若把 cinder 主题放到 mkdocs/docs/ 下面, 要指定以 root 为 mkdocs, 对应路径为docs/cinder

1.8.2 name: null  自定义主题

以 cinder 主题来说, 这个主题仅仅是个文件夹, 直接用 name: cinder 无法识别. 可以指定 name: null, 结合 custom_dir: docs/cinder 来实现.

1.9 关于 css 文件的生效优先级文件说明

1.9.1 css 优先级1, 默认主题内 css 的优先级

从~/bin/mkdocs/docs/cinder » code base.html 如下位置知道此主题的默认 css 路径,和载入顺序, 越下面的优先级越高.

    <link href="{{ 'css/bootstrap-custom.min.css'|url }}" rel="stylesheet">
    <link href="{{ 'css/base.min.css'|url }}" rel="stylesheet">
    <link href="{{ 'css/cinder.min.css'|url }}" rel="stylesheet">

另外, 从上面的 code 也能知道, 主题里面载入的只有 *. min.css, 不会载入不带 mini 的.

.
├── base.css
├── base.min.css
├── bootstrap-custom.css
├── bootstrap-custom.min.css
├── cinder.css
├── cinder.min.css
├── highlight.css
└── highlight.min.css

mini.css 是压缩过的, 文件小, 但不方便读取.

而不带 mini 的比较大, 排版好, 方便人读取.

1.9.2 css 优先级 2, extra_css 内的优先级

extra_css 路径: 根路径root 是mkdocs/docs , 然后下面要一个一个 css 明确指定.

extra_css:
  - css/base.css
  - css/bootstrap-custom.css
  - css/highlight.css
  - css/cinder.css

1. extra_css 文件夹相对主题里面的 css, 是后载入的. 故比主题里面的优先级高.

2. extra_css 文件夹里面的优先级, 越后面的优先级越高. 故 cinder.css 优先级最高.

Tips:

建议把主题里面的不带 mini 字样的 css 丢到 extra_css 里面.

这样, 可以用 extra_css 里面的同样选择器的配置覆盖默认主题的.

同时保证了默认主题里面的 mini.css 载入快, 而 extra_css 里面的 css 方便人阅读.

1.10 部署

其实 1.2 节仅仅算在线测试, 最终还是要生成静态文件后, 把静态文件传到服务器上运行的.

若仅仅 1.2 丢都服务器上, 那就算动态网站, 而不是静态的了.

2 附件: 配置文件参考.

~/bin/mkdocs » tree -L 2                                                                                     1 ↵ zh0ngx1ngzhe-su@Klg
.
├── docs
│   ├── about.md
│   ├── cinder
│   ├── css
│   ├── img
│   ├── index2.md
│   ├── index.md
│   ├── specimen.md
│   └── V000-VPS
├── mkdocs.yml


10 directories, 9 files
-------------------------------------------------------------------------------------------------------------------------------------
~/bin/mkdocs »  


./mkdocs/mkdocs.yml

extra_css:
  - css/base.css
  - css/bootstrap-custom.css
  - css/highlight.css
  - css/cinder.css
theme:
    name: null
    custom_dir: docs/cinder
    highlightjs: true