Markdown转静态网站

工具

mkdocs-material

官网：https://squidfunk.github.io/mkdocs-material/

安装

pip install mkdocs-material

如果没有 pip 先安装 python

安装完成后运行 mkdocs

如果出现 mkdoc 不是内部或外部命令，也不是可运行的程序
或批处理文件

需要设置环境变量

使用

mkdocs new my_project

编辑 mkdocs.yml

theme:
  name: material

更多 mkdocs.yml 配置查看 mkdocs 官方网站

以下为 mkdocs 官方样例

# Copyright (c) 2016-2021 Martin Donath <martin.donath@squidfunk.com>

# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:

# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.

# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

# 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

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

# Copyright
copyright: Copyright &copy; 2016 - 2021 Martin Donath

# Configuration
theme:
  name: null
  custom_dir: !ENV [THEME_DIR, "material"]

  # Static files
  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:
    - content.code.annotate
    - content.tabs.link
    # - header.autohide
    # - navigation.expand
    # - navigation.indexes
    # - navigation.instant
    - navigation.sections
    - navigation.tabs
    # - navigation.tabs.sticky
    - navigation.top
    - navigation.tracking
    - search.highlight
    - search.share
    - search.suggest
    # - toc.integrate
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode
    - scheme: slate
      primary: red
      accent: red
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode
  font:
    text: Roboto
    code: Roboto Mono
  favicon: assets/favicon.png
  icon:
    logo: logo

# Plugins
# plugins:
#   - search
#   - redirects:
#       redirect_maps:
#         changelog/insiders.md: insiders/changelog.md
#         extensions/admonition.md: reference/admonitions.md
#         extensions/codehilite.md: reference/code-blocks.md
#         extensions/footnotes.md: reference/footnotes.md
#         extensions/metadata.md: reference/meta-tags.md
#         extensions/permalinks.md: setup/setting-up-navigation.md #permalink
#         extensions/pymdown.md: reference/admonitions.md
#         plugins/revision-date.md: setup/adding-a-git-repository.md #revision-date
#         plugins/search.md: setup/setting-up-site-search.md
#         releases/4.md: upgrading.md #upgrading-from-4x-to-5x
#         releases/5.md: upgrading.md #upgrading-from-3x-to-4x
#         releases/changelog.md: changelog.md
#         setup/adding-social-links.md: setup/setting-up-the-footer.md
#         sponsorship.md: insiders/index.md
#   - minify:
#       minify_html: true

# Customization
extra:
  analytics:
    provider: google
    property: !ENV GOOGLE_ANALYTICS_KEY
  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:
  - admonition
  - abbr
  - attr_list
  - def_list
  - footnotes
  - meta
  - md_in_html
  - toc:
      permalink: true
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - pymdownx.highlight
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.magiclink:
      repo_url_shorthand: true
      user: squidfunk
      repo: mkdocs-material
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid-experimental
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

# Page tree
nav:
  - Home: index.md
  - Getting started:
    - Installation: getting-started.md
    - Creating your site: creating-your-site.md
    - Publishing your site: publishing-your-site.md
    - Customization: customization.md
    - Troubleshooting: troubleshooting.md
    - Data privacy: data-privacy.md
    - License: license.md
    - Releases:
      - Changelog: changelog.md
      - Upgrade guide: upgrading.md
      - Deprecations: deprecations.md
  - Setup:
    - Changing the colors: setup/changing-the-colors.md
    - Changing the fonts: setup/changing-the-fonts.md
    - Changing the language: setup/changing-the-language.md
    - Changing the logo and icons: setup/changing-the-logo-and-icons.md
    - Setting up navigation: setup/setting-up-navigation.md
    - Setting up site search: setup/setting-up-site-search.md
    - Setting up site analytics: setup/setting-up-site-analytics.md
    - Setting up social cards: setup/setting-up-social-cards.md
    - Setting up tags: setup/setting-up-tags.md
    - Setting up versioning: setup/setting-up-versioning.md
    - Setting up the header: setup/setting-up-the-header.md
    - Setting up the footer: setup/setting-up-the-footer.md
    - Adding a git repository: setup/adding-a-git-repository.md
    - Adding a comment system: setup/adding-a-comment-system.md
  - Reference:
    - Abbreviations: reference/abbreviations.md
    - Admonitions: reference/admonitions.md
    - Buttons: reference/buttons.md
    - Code blocks: reference/code-blocks.md
    - Content tabs: reference/content-tabs.md
    - Data tables: reference/data-tables.md
    - Diagrams: reference/diagrams.md
    - Footnotes: reference/footnotes.md
    - Formatting: reference/formatting.md
    - Icons + Emojis: reference/icons-emojis.md
    - Images: reference/images.md
    - Lists: reference/lists.md
    - MathJax: reference/mathjax.md
    - Meta tags: reference/meta-tags.md
    - Variables: reference/variables.md
  - Insiders:
    - Sponsorship: insiders/index.md
    - Getting started:
      - Installation: insiders/getting-started.md
      - Changelog: insiders/changelog.md

运行

mkdocs serve

构建静态站点

mkdocs build

更多功能参照官方文档