跳转至

文档结构说明

先介绍一下网页各部分的称呼

alt

关于安装

关于Mkdocs相关环境的安装, 见Gitee页。

本文档使用的是Mkdocs-Material主题，具体见Material文档

mkdocs.yml

mkdocs.yml是文档的配置文件，位于Yukarifans_Mkdocs/YukariFans目录下，使用的是yaml的语法（注意首行缩进）

Plugins外的大部分配置可以在Material文档找到定义和使用例。

介绍一下yml文件内各个部分的含义：

  • 目前激活的插件
plugins:
  - 插件名称
  • 配置pymarkdown库的各个属性，pymarkdown具体语法见其文档
markdown_extensions:
  - 配置名称
  • 自定义的页面样式，可以覆盖mkdocs-material自带的样式 目前页面的颜色就是自定义的
extra_css:
  #css文件的相对于docs文件夹的路径
  - html/css/extra.css
  • 额外的js代码
extra_javascript:
  #js文件的相对于docs文件夹的路径, 这个js可以自定义一些快捷键
  - html/javascripts/shortcuts.js
  • 配置当前使用的主题及其各个属性
theme:
  name: "material"
  custom_dir: overrides
  • 配置页面底部，如添加友链，展示备案号之类的
extra:
  - 各个配置
  • 网站名和网站url
site_name: Kotonofans
site_url: "https://saisui.github.io/kotonofans/"

.pages

需要awesome-pages插件才能使用，具体可以参考文档。

.pages 文件主要用于方便管理导航（Navigation）的条目, 和根据导航自动生成的顶部导航(Tab)

  • 其具有以下属性可以配置，更多属性看其文档

title: 设置后，覆盖导航原本显示的标题 nav: 导航的条目, ...表示将目录剩下的所有md都加进来 hide: 设为true时,从导航中隐藏该条目，包含所有子文件和子文件夹

例子
.pages 例子1
title: 文档编辑帮助
nav:
  - start.md
  - ...
  - end.md
.pages 例子2
title: 文档编辑帮助
nav:
  - ... | *说明.md # 【... |】 后边接正则表达式
.pages 例子3
nav:
  - introduction.md
  - 自定义名:
      - 自定义名1: page1.md
      - 自定义名2: page2.md
      - Link Title: 一个链接
  - Section 2:
      - ...
hide: true
注意

保证每个放md文档的文件夹内都有一个.page文件

为什么用这种方式管理条目

mkdocs提供的navigation属性(在mkdocs.yml中配置)需要将所有md文档一个一个添加到nav条目中，一旦条目过多非常容易出问题。.pages文件相当于将mkdocs.yml中的navigation拆开，在每个文件夹中分别生成navigation，且提供...的批处理和正则表达式的批处理。

blogs.md

用于存放博客页面，该页面根据 md文件设置的 time/date 元数据属性从早到晚展示，就像博客一样。

mkdocs.yml中设置的文件夹和其子文件夹的文档才会出现在博客页。

plugins:
  - blogging: #生成博客页
      dirs: # The directories to be included
        - help

tags.md

用于存放标签页面，该页面根据 md文件设置的 tags 元数据属性来分类文档。

site文件夹

mkdocs build 或 mkdocs gh-deploy 后生成的静态站点，可以不用管。

override文件夹

在mkdocs.yml中设为了自定义样式文件夹，用于覆盖mkdocs-meterial html 的各个块。参考链接

docs/assets文件夹

存放资源文件，如果有本体图片，可以存在assets下新建的image文件夹中。

如html相关的文件，如html，css，javascript。

回到页面顶部