基于Material for MkDocs搭建静态网页 2020年06月10日 IT Tech 0次评论 2137次阅读 2757字数 预计阅读时间7分钟 MkDocs 静态网页 Github ### 介绍 [MkDocs](https://www.mkdocs.org/) 是一个简单好用的静态网页生成器,而 [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) 是 Mkdocs 根据 Google 的 Material Design 指南构建的专门用于项目文档的一款主题。  本文基于 **Material for Mkdocs** 来搭建简洁、漂亮的静态网页,并部署在 **GitHub Homepage** 上,不需要额外搭建服务器,没有网页设计基础也可简单完成: - Python 模块,符合 **Google Material UI** 规范的自定义主题; - 针对特定语法、功能做了渲染优化; - 根据客户端浏览器页面尺寸自动缩放,对 PC、移动设备都友好; - 丰富的页面配色,多达 **19** 种主体配色和 **16** 种悬停链接文字配色; - 支持多语言搜索; - 支持添加 **Disqus** 用户评论功能; - 支持统计功能,如百度统计,谷歌统计; ### 安装 Mkdocs && Material 在终端中使用 `pip` 安装 Material ```Python pip install mkdocs mkdocs-material ``` - 在使用 pip 安装前,确保已安装 Python,本文使用的 Python 版本为 Python 3.7.4. 安装完成后,验证 Mkdocs 版本 ```Bash mkdocs --version # mkdocs, version 1.1 ``` - Material requires MkDocs >= 1.0.0. ### 创建新项目 ```Bash mkdocs new my-project # “my-project”为项目名称,可自定义 ``` 此时在当前路径下会生成一个名为”my-project“的文件夹,打开该文件夹可发现,它包含如下文件: ```Bash my-project/mkdocs.yml # YAML 配置文件 my-project/Docs/index.md # 主页内容 ``` ### 配置 YAML 文件 #### 项目信息 - site_name 这是必要的设置,并且应该是一个字符串,用作项目文档的主要标题。例如: ```YAML site_name: My Docs ``` 渲染主题时,此设置将作为`site_name`上下文变量传递。 - site_url 设置网站的URL地址。例如: ```YAML site_url: https://xxxx.github.io ``` **默认值**:`null` - site_description 设置站点说明,这会将meta标签添加到生成的HTML标头中。 **默认值**:`null` - site_author 设置作者的姓名,这会将meta标签添加到生成的HTML标头中。 **默认值:**`null` - repo_name 存储库名称,设置后在每个页面上提供指向您的存储库的链接的名称。 **默认值**:`'GitHub'`,`'Bitbucket'`或者`'GitLab'`如果`repo_url`匹配这些域,则为的主机名`repo_url`。 - repo_url 存储库地址,设置后在每个页面上提供指向您的存储库(GitHub,Bitbucket,GitLab等)的链接。例如: ```YAML repo_url: https://github.com/example/repository/ ``` **默认值**:`null` - edit_uri 在线编辑路径,设置后,直接提供一个链接到源存储库中的页面。这使查找和编辑页面源变得更加容易。如果`repo_url`未设置,则忽略此选项。 **默认值**:`edit/master/docs/`用于GitHub和GitLab存储库或 `src/default/docs/`Bitbucket存储库(如果`repo_url`与这些域匹配),否则`null` - 对于GitHub或GitLab托管的存储库,`edit_uri` 将自动设置为`edit/master/docs/`(请注意`edit`路径和`master`分支)。* 对于由Bitbucket托管的存储库,等效项`edit_uri`将自动设置为`src/default/docs/`(请注意`src`路径和`default` 分支)。* 要使用与默认值不同的URI(例如,不同的分支),只需将设置`edit_uri`为所需的字符串。如果您不希望在页面上显示任何“编辑URL链接”,请设置`edit_uri`为空字符串以禁用自动设置。* 在GitHub和GitLab上,默认的“编辑”路径(`edit/master/docs/`)在在线编辑器中打开页面。此功能要求用户拥有并登录到GitHub / GitLab帐户。否则,用户将被重定向到登录/注册页面。或者,使用“ blob”路径(`blob/master/docs/`)打开一个只读视图,该视图支持匿名访问。 - docs_dir 包含文档源markdown文件的目录。它可以是相对目录,在这种情况下,它是相对于包含您的配置文件的目录来解析的,或者可以是从本地文件系统根目录开始的绝对目录路径。 **默认值**:`'docs'` - copyright 设置要通过主题包含在文档中的版权信息。例如: ```YAML copyright: "Copyright © 2019 - 2020 xxxx" ``` **默认值**:`null` #### 页面风格 #### 启用 material 主题 ```YAML theme: name: 'material' ``` #### 配色 在Google的Material Design [调色板上](http://www.materialui.co/colors),为每种主题色和强调色定义了默认色相,这使更改主题的整体外观非常容易。只需使用以下变量设置原色和强调色: ```YAML theme: palette: primary: 'indigo' 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 `和 `white`。后四种颜色只能用作主题色。 **主题色**  **强调色**  #### 网页Logo Logo 应为矩形,最小分辨率为128x128,留出一定的边缘空间,并在透明地面上由高对比度区域组成,因为它将放置在彩色标题栏。只需创建文件夹`docs/images`,添加Logo并将其嵌入: ```YAML theme: logo: 'images/logo.svg' ``` **默认值**: `school` 此外,可以通过从[Material Design图标字体中](https://material.io/icons/)设置任意连字(或Unicode代码点)来更改默认图标,例如: ```YAML theme: logo: icon: 'cloud' ``` #### 网站图标 可以通过将`favicon`变量设置为`.ico`或图像文件来更改默认图标。 ```YAML theme: favicon: 'assets/images/favicon.ico' ``` **默认值**:`assets/images/favicon.png` #### 文本风格 #### 语言 通过以下方式指定语言: ```YAML theme: language: 'en' ``` material for mkdocs 支持国际化(i18n),并提供以下语言的所有模板变量和标签的翻译: |Available languages||| |-|-|-| |`af` / Afrikaans|`ar` / Arabic|`ca` / Catalan| |`cs` / Czech|`et` / Estonian|`de` / German| |`hr` / Croatian|`ja` / Japanese|`ro` / Romanian| |`da` / Danish|`nl` / Dutch|`en` / English| |`fi` / Finnish|`fr` / French|`gl` / Galician| |`gr` / Greek|`he` / Hebrew|`hi` / Hindi| |`hu` / Hungarian|`id` / Indonesian|`it` / Italian| |`kr` / Korean|`no` / Norwegian|`nn` / Norwegian| |`fa` / Persian|`pl` / Polish|`pt` / Portugese| |`ru` / Russian|`sr` / Serbian|`sh` / Serbo-Croatian| |`sk` / Slovak|`th` / Thai|`vi` / Vietnamese| |`si` / Slovenian|`es` / Spanish|`sv` / Swedish| |`tr` / Turkish|`uk` / Ukrainian|`zh` / Chinese (Simplified)| |`zh-TW` / Chinese (Taiwanese)||`zh-Hant` / Chinese (Traditional)| #### 字体 默认情况下,主题包含[Roboto字体系列](https://fonts.google.com/specimen/Roboto),尤其是文本的常规 sans-serif 类型和`monospaced`代码的类型。两种字体均从[Google字体](https://fonts.google.com/)加载,并且可以更改为其他字体,例如[Ubuntu字体家族](https://fonts.google.com/specimen/Ubuntu): ```YAML theme: font: text: 'Ubuntu' code: 'Ubuntu Mono' ``` 文本字体将以权重400和700加载,`monospaced`字体以常规权重加载。如果您想从其他目标加载字体,或者不想使用Google字体加载,只需将其设置`font`为`false`: ```YAML theme: font: false ``` **默认值**:`Roboto`和`Roboto Mono` #### 文本方向 material 同时支持从左到右(`ltr`)和从右到左(`rtl`)文本方向。这使更多语言(例如阿拉伯语,希伯来语,叙利亚语和其他语言)可以与主题一起使用: ```YAML theme: direction: 'rtl' ``` **默认值**:与给定主题语言的最佳匹配,自动设置 #### 标签 默认情况下,整个导航在左侧使用可折叠部分呈现,因为水平导航在较小的屏幕上经常会出现问题。但是,对于大型文档项目,有时需要添加另一个导航层来分隔顶层部分。material 通过 tabs 功能实现了这一点,可以通过将相应功能标记设置为来启用`true`: ```YAML theme: feature: tabs: true ``` **默认值**:`fasle` - 启用标签页后,*顶层区域*将在标题正下方的附加层中呈现。左侧的导航将仅包含所选部分中包含的页面。此外,在项目的内部定义的*顶级页面*`mkdocs.yml`将被分组在第一个选项卡下,该选项卡将接收第一页的标题。 #### 导航栏 用于确定站点的全局导航的格式和布局。最简单的导航配置如下所示: ```YAML nav: - 'index.md' - 'about.md' ``` - 导航配置中的所有路径都必须相对于`docs_dir` 配置选项。如果该选项设置为默认值,`docs`则上述配置的源文件将位于`docs/index.md`和 `docs/about.md`。 上面的示例将导致在顶层创建两个导航项,并根据Markdown文件的内容(如果在文件中未定义标题的话)从文件名推断其标题。要覆盖`nav`设置中的标题,请在文件名之前添加一个标题: ```YAML nav: - Home: 'index.md' - About: 'about.md' ``` - 如果在导航中为页面定义了标题,则该标题将在该页面的整个站点中使用,并将覆盖页面本身内定义的任何标题。 可以通过在部分标题下列出相关页面来创建导航子部分。例如: ```YAML nav: - Home: 'index.md' - User Guide: - 'Writing your docs': 'writing-your-docs.md' - 'Styling your docs': 'styling-your-docs.md' - About: - 'License': 'license.md' - 'Release Notes': 'release-notes.md' ``` 通过上述配置,我们具有三个顶级项:“主页”,“用户指南”和“关于”。“首页”是指向该网站首页的链接。在“用户指南”部分下,列出了两个页面:“编写文档”和“样式化文档”。在“关于”部分下,又列出了两个页面:“许可证”和“发行说明”。 #### 扩展功能 #### 网站搜索 网站搜索是使用[lunr.js](https://lunrjs.com/)实现的,该默认情况下包括英语的单词,而其他语言的词干包含在[lunr-languages中](https://github.com/MihaiValentin/lunr-languages),这两种[语言](https://github.com/MihaiValentin/lunr-languages)都与此主题集成在一起。素材为给定的主题语言选择匹配的(或最匹配的)词干。`mkdocs.yml`通过显式定义搜索语言,可以在项目的语言中激活多语言搜索: ```YAML extra: search: language: 'en, de, ru' ``` |Available language|||| |-|-|-|-| |`da` / Danish|`du` / Dutch|`en` / English|`fi` / Finnish| |`fr` / French|`de` / German|`hu` / Hungarian|`it` / Italian| |`ja` / Japanese|`no` / Norwegian|`pt` / Portugese|`ro` / Romanian| |`ru` / Russian|`es` / Spanish|`sv` / Swedish|`tr` / Turkish| 可以对词的分隔符进行自定义,这可以索引由`-`或分隔的单词部分`.`: ```YAML extra: search: tokenizer: '[\s\-\.]+' ``` - 目前,Lunr语言不支持中文或其他亚洲语言。但是,实践证明,可使用日语来搜索中文。 #### 社交关系 在文档的页脚中链接社交帐户。`type`必须表示类型,例如`github`,`twitter`或者`linkedin`,`link`必须包含要链接的网址,例如: ```YAML extra: social: - type: 'github' link: 'https://github.com/xxxx' - type: 'twitter' link: 'https://twitter.com/xxxx' - type: 'linkedin' link: 'https://www.linkedin.com/in/xxxx' ``` #### 谷歌分析 设置Google Analytics(分析)跟踪配置。MkDocs可轻松将网站跟踪与Google Analytics(分析)集成。除了基本跟踪之外,还可以跟踪所有传出链接的点击以及网站搜索的使用方式。可以在项目的中激活跟踪: ```YAML google_analytics: - 'UA-XXXXXXXX-X' - 'auto' ``` #### 评论插件 material 已与[Disqus](https://disqus.com/) 集成在一起,因此,如果要在文档中添加注释部分,只需设置你在 Disqus 里的简称: ```YAML extra: disqus: 'your-shortname' ``` - 除了索引页面之外,所有页面上都会插入注释部分。此外,将在目录底部生成一个新条目,该条目链接到注释部分。 - `site_url`必须设置值,以使Disqus集成正确加载。 也可以使用在 markdown_extensions 安装 meta 为特定页面启用或禁用 Disqus (下述)。 #### Markdown扩展 MkDocs页面必须使用[Markdown](https://daringfireball.net/projects/markdown/)写作,Markdown是一种轻量级的标记语言,它导致易于阅读,易于编写的纯文本文档,并且可以以可预测的方式转换为有效的HTML文档。 MkDocs使用[Python-Markdown](https://python-markdown.github.io/)库将Markdown文档呈现为HTML。除了在所有Markdown实现中通用的 [基本Markdown语法](https://daringfireball.net/projects/markdown/syntax),MkDocs还支持通过 [Python-Markdown扩展](https://python-markdown.github.io/extensions/) 语法。建议默认启用以下扩展: ```YAML markdown_extensions: - admonition # 注解块支持 - pymdownx.arithmatex # 数学公式的TeX语法支持 - pymdownx.betterem: smart_enable: all - pymdownx.caret - pymdownx.critic - pymdownx.details - pymdownx.emoji: # 表情支持 emoji_generator: !!python/name:pymdownx.emoji.to_svg - pymdownx.inlinehilite - pymdownx.magiclink - pymdownx.mark - pymdownx.smartsymbols - pymdownx.superfences - pymdownx.tasklist: # 任务清单支持 custom_checkbox: true - pymdownx.tilde - meta # 元数据支持 ``` - 使用 **arithmatex** 时,除了激活扩展之外,还需要在`mkdocs.yml`中包括MathJax JavaScript: ```YAML extra_javascript: - 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML' ``` - 使用 **meta** ,为特定页面启用或禁用 Disqus: 元数据在Markdown文档的开头以一系列键值对的形式编写,并由结束元数据上下文的空白行分隔。 ```YAML # 可以在每个文档启用Disqus: disqus: your-shortname # 可以通过将特定页面设置为空值来禁用Disqus: disqus: ``` ### 开发服务器 MkDocs包含一个开发服务器,因此可以随时在本地进行浏览、更改。 在 mkdocs.yml 同一路径下,使用以下命令启动开发服务器: ```YAML mkdocs serve ``` 现在,可以将浏览器中输入地址 [http://localhost:8000](http://localhost:8000/), 来预览网页效果。 ### 生成网页 在 mkdocs.yml 同一路径下,使用以下命令依据 mkdocs.yml 配置文件,生成网页: ```YAML mkdocs build ``` 成功后,将在项目文件夹下生成一个名为 site 的文件夹,其中包含了所有生成的网页。 将 **site 文件夹下的所有文件**拷贝到项目根目录下,与 **docs文件夹及其包含的文本**,共同组成**网页资源**。 当我们部署网页时,只需要将上述**网页资源**进行部署即可(**忽略 mkdocs.yml 和 site 文件夹**)。 ### 将网页部署到 GitHub Pages #### Step 1 创建新仓库 登录 [GitHub](https://github.com),在右上角选择 New repository,创建新仓库。  #### Step 2 配置仓库信息 在仓库设置页面,**Repository_name**设置成 **xxxx**.github.io,其中 **xxxx** 是你 GitHub 的用户名。 选择 **Public** ,点击 **Create repository**.  #### Step 3 上传网页资源到仓库 将生成的网页资源上传到刚刚创建的仓库中(使用 Git 相关命令或直接使用 GitHub Desktop 软件进行操作,这里不再叙述)。  #### Step 4 部署到 GitHub Pages 打开仓库,点击仓库功能栏的 **Setting**,进入到仓库设置页面。 在设置页面找到 **GitHub Pages** 部分,在 **Source** 这里选择 **master branch**。  部署成功后,便可以通过 [**xxxx.github.io**](http://xxxx.github.io) 来访问你的网页。 ### 效果展示 [https://Derrors.github.io](https://Derrors.github.io) ### Reference [https://www.mkdocs.org/](https://www.mkdocs.org/) [https://squidfunk.github.io/mkdocs-material/](https://squidfunk.github.io/mkdocs-material/) 本文由 Derrors 创作,采用 知识共享署名4.0 国际许可协议. 最后编辑时间: 2021年01月28日 21:36.