使用Mkdocs+Mkdocs-Material搭建静态文档网站

0.前言

和WordPress这样的博客框架一样,文档也有类似的框架,Mkdocs 可以使我们快速通过md文件创建静态文档网站.

1.什么是Mkdocs

MkDocs 是一个快速、简单、华丽的静态站点生成器，适用于构建项目文档。文档源文件使用 Markdown 编写，并使用单个 YAML 配置文件进行配置。

2.什么是Mkdocs-Material

Mkdocs-Material基于Mkdocs,可以理解为是Mkdocs的一个主题.
从一组 Markdown 文件中创建一个品牌静态网站，用于托管您的开放源码或商业项目的文档——可定制、可搜索、方便移动、支持40多种语言.

3.安装

mkdocs安装教程 - 软件开发 - 方帮信 (fangbangxin.com)这里有详细的安装教程

3.1 安装Python环境

Welcome to Python.org

前往Python官网,下载对应系统版本的Python安装即可.

#查看python是否安装成功
python
#返回:Python 3.10.7,或其他版本,则表示python环境安装成功

3.2 安装Mkdocs

pip install mkdocs

3.3 安装Mkdocs-Material

pip install mkdocs-material

4.开始

# 新建项目
mkdocs new project-doc
# 将 markdown 文件放入 doc 文件夹
# 构建
mkdocs build # 生成 html
# 本地服务
mkdocs serve
# 打开
start 127.0.0.1:8000

5.官方参考mkdocs.yml

# Project information
site_name: Material for MkDocs
site_url: https://squidfunk.github.io/mkdocs-material/
site_author: Martin Donath
site_description: >-
  Create a branded static site from a set of Markdown files to host the
  documentation of your Open Source or commercial project – customizable,
  searchable, mobile-friendly, 40+ languages

# Repository
repo_name: squidfunk/mkdocs-material
repo_url: https://github.com/squidfunk/mkdocs-material
edit_uri: ""

# Copyright
copyright: Copyright © 2016 - 2020 Martin Donath

# Configuration
theme:
  name: null
  custom_dir: material

  # 404 page
  static_templates:
    - 404.html

  # Don't include MkDocs' JavaScript
  include_search_page: false
  search_index_only: true

  # Default values, taken from mkdocs_theme.yml
  language: en
  features:
    - tabs
    #- instant
  palette:
    scheme: default
    primary: indigo
    accent: indigo
  font:
    text: Roboto
    code: Roboto Mono
  icon:
    logo: logo
  favicon: assets/favicon.png

# Plugins
plugins:
  - search
  - minify:
      minify_html: true

# Customization
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/squidfunk
    - icon: fontawesome/brands/gitter
      link: https://gitter.im/squidfunk/mkdocs-material
    - icon: fontawesome/brands/docker
      link: https://hub.docker.com/r/squidfunk/mkdocs-material/
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/squidfunk
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/squidfunk/
    - icon: fontawesome/brands/instagram
      link: https://instagram.com/squidfunk

# Extensions
markdown_extensions:
  - markdown.extensions.admonition
  - markdown.extensions.attr_list
  - markdown.extensions.codehilite:
      guess_lang: false
  - markdown.extensions.def_list
  - markdown.extensions.footnotes
  - markdown.extensions.meta
  - markdown.extensions.toc:
      permalink: true
  - pymdownx.arithmatex
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  # - pymdownx.highlight:
  #     linenums_style: pymdownx-inline
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.magiclink:
      repo_url_shorthand: true
      user: squidfunk
      repo: mkdocs-material
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.snippets:
      check_paths: true
  - pymdownx.superfences
  - pymdownx.tabbed
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

# Page tree
nav:
  - Home: index.md
  - Getting started: getting-started.md
  - Extensions:
    - Admonition: extensions/admonition.md
    - CodeHilite: extensions/codehilite.md
    - Footnotes: extensions/footnotes.md
    - Metadata: extensions/metadata.md
    - Permalinks: extensions/permalinks.md
    - PyMdown: extensions/pymdown.md
  - Plugins:
    - Search: plugins/search.md
    - Minification: plugins/minification.md
    - Revision date: plugins/revision-date.md
    - Awesome pages: plugins/awesome-pages.md
  - Releases:
    - Upgrading to 5.x: releases/5.md
    - Upgrading to 4.x: releases/4.md
    - Changelog: releases/changelog.md
  - Customization: customization.md
  - Data privacy: data-privacy.md
  - Contributing: contributing.md
  - License: license.md

# Google Analytics
google_analytics:
  - !!python/object/apply:os.getenv ["GOOGLE_ANALYTICS_KEY"]
  - auto

6.笔者自用Mkdocs.yml

site_name: UnityShaderGraphNote

#使用时请删除所有注释!!!#

markdown_extensions: #Markdown拓展,添加之后可以支持更多的Markdown语法#
  - pymdownx.arithmatex
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - pymdownx.inlinehilite
  - pymdownx.magiclink
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tabbed
  - pymdownx.tilde
  

theme:
    name: "material" #使用Mkdocs-Material主题#
    
    palette:
        primary: "black" #设置主题颜色为黑色#
        accent: "deep orange"
        language: "zh" #设置主题语言为中文#
      

   
 

7.通过MD文件生成的网站预览