使用mkdocs搭建文档系统(使用material主题美化)

汪典
2023-12-01

material是一个mkdocs主题,它的优点:

  • 谷歌的material设计风格。

  • 渐进式布局,可以适配各种设备访问。

  • 支持非常多的插件和扩展,个人试过不少mkdocs主题,material的可扩展性是最好的。

安装

pip install mkdocs-material

在配置文件中添加:

theme:
	name: 'material'

配置

放一个我的配置文件:

theme:
    name: "material"
    logo:
        icon: "mkdocs"
    palette:
        primary: "black"
        accent: "deep orange"
    language: "zh"

主题名字

name属性就是主题的名字,我们使用的是material。

logo图标

logo会在网页的左上角显示出来,可以是一个文字或者是图片。

如果是图片可以用这样的形式:

theme:
  logo: 'images/logo.svg'

上面的例子mkdocs会在docs目录下搜索images的目录,所以前提是要你有这个文件。

调色盘

palette下有两个属性。

  • primary就是你主题的主色调,它会影响你的header,footer等等的背景色。
  • accent的颜色在你点击链接的时候就能看出来。
  • 具体效果,官方有个调色盘可以让你试验一下这些颜色的变化。

颜色的设置默认都是indigo颜色,其他颜色可供参考的选项:

Red Pink Purple Deep Purple Indigo Blue Light Blue Cyan Teal Green Light Green Lime Yellow Amber Orange Deep Orange Brown Grey Blue Grey Black White

最后的5种颜色不能用在accent上。

语言

language不用说。

很多mkdocs的主题到现在还不支持这个中文选项,material支持,但是其实没什么关系。

友情链接

extra:
  social:
    - type: 'github'
      link: 'https://github.com/squidfunk'
    - type: 'twitter'
      link: 'https://twitter.com/squidfunk'
    - type: 'linkedin'
      link: 'https://www.linkedin.com/in/squidfunk'

在extra的social属性可以定义友情链接。

 类似资料: