使用MkDocs Material Theme和github创建自己的网页

本文链接：https://blog.csdn.net/m0_74397775/article/details/141360699

参考：

https://www.youtube.com/watch?v=Q-YA_dA8C20

Publish a Website with Material for MkDocs and GitHub Pages - 杨希杰的个人网站

GitHub Pages | Websites for you and your projects, hosted directly from your GitHub repository. Just edit, push, and your changes are live.

准备的工具：

python
github CLI
vs code

1. 在Github中创建一个库

New repository

起一个名字，e.g. yeezyshappybook
设置权限：public or private
☑️勾选Add a Readme File
.gitgnore template选择Python
LICENSE 选择GNU General Public License v3.0
最后选择创建

2. 把这个库clone到本地并进行一些部署

复制SSH

进入终端

git clone git@github.com:yeezy1103/yeezyshappybook.git #替换成自己的SSH
cd yeezyshappybook # 进入到这个文件夹中
python -m venv venv-notebook # 创建一个虚拟环境
source vent-notebook/bin/activate # 激活虚拟环境
pip install mkdocs-material 
code . # 进入vscode

在vscode中打开终端

mkdocs new .
mkdocs serve # 然后按住command+单击url以进入网页

👆这个时候的网页不是特别的漂亮，这是mkdocs默认的样式

theme:
  name: material

再一次进入网页可以看见已经大改变了

3. 添加页面

4. 配置文件

mkdocs.yml

注意修改第二行

# [Info]
# 左上角标题
site_name: yeezyshappyhome
site_url: https://yeezy1103.github.io
site_author: 叶芷延
site_description: 叶芷延的个人网站

theme:
  name: material
  # [切换日间模式和夜间模式]
  # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#color-palette-toggle
  palette:
    # 日间模式
    - scheme: default
      # 主颜色
      # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#primary-color
      primary: teal
      # 链接等可交互元件的高亮色
      # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#accent-color
      accent: orange
      toggle:
        # 图标
        icon: material/weather-night
        # 鼠标悬浮提示
        name: 切换至夜间模式
    # 夜间模式
    - scheme: slate
      primary: indigo
      accent: orange
      toggle:
        icon: material/weather-sunny
        name: 切换至日间模式
  features:
    # 使用 Tab 来进行分类
    # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-tabs
    - navigation.tabs
    # 返回顶部的按钮，在上滑时出现
    # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#back-to-top-button
    - navigation.top
    # 给每个 Tab 添加一个 index.md，且在点击 Tab 时打开
    # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#section-index-pages-with-section-index-pages
    - navigation.indexes
    # 打开 Tab 时左侧目录全部展开
    # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-expansion
    - navigation.expand
    # 搜索输入一些字母时推荐补全整个单词
    # https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-suggestions
    - search.suggest
    # 搜索的关键词文章加入高亮
    # https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-highlighting
    - search.highlight
    # 可以通过按钮复制代码
    # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-copy-button
    - content.code.copy
    # [点击按钮跳转至 GitHub 修改 Markdown 源文件]
    # https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#code-actions
    - content.action.edit
  language: zh # 一些提示性的文字会变成中文
  icon:
    # [添加 GitHub 仓库]
    # https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#repository-icon
    repo: fontawesome/brands/github
# [点击按钮跳转至 GitHub 修改 Markdown 源文件]
# https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#code-actions
edit_uri: edit/main/docs/
# [top-right corner]
# [添加 GitHub 仓库]
# https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/
repo_url: https://yeezy1103.github.io/yeezyshappybook/
repo_name: yeezy1103.github.io
# [bottom-left corner]
# [版权说明]
# https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/#copyright-notice
copyright: 叶芷延
# [bottom-right corner]
extra:
  # [添加社交网络图标和链接]
  # https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/#social-links
  # 搜索图标：https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search
  # name 会在鼠标悬浮时提示
  social: # icons
    - name: GitHub | Yeezy
      icon: fontawesome/brands/github
      link: https://github.com/Yeezy1103
    # - name: Bilibili | 杨希杰619
    #   icon: fontawesome/brands/bilibili
    #   link: https://space.bilibili.com/24502827
    # - name: 小杰答疑群 QQ 796233390
    #   icon: fontawesome/brands/qq
    #   link: https://yang-xijie.github.io/ME/qq-groups/
    # - name: 小杰水群 QQ 824114857
    #   icon: fontawesome/brands/qq
    #   link: https://yang-xijie.github.io/ME/qq-groups/
    # - name: 小红书 | 杨希杰
    #   icon: fontawesome/solid/images
    #   link: https://www.xiaohongshu.com/user/profile/61be0cc10000000021024369
    # - name: 打赏支持
    #   icon: fontawesome/solid/mug-saucer
    #   link: https://yang-xijie.github.io/ME/support/

# [Extensions]
plugins:
  # [搜索功能]
  # https://squidfunk.github.io/mkdocs-material/plugins/search/
  # 之前中文搜索是 Insider 的功能（https://squidfunk.github.io/mkdocs-material/blog/2022/chinese-search-support/），现在好像已经是默认功能了，
  - search:
      lang:
        - zh
        - en
        - ja
  # [给单篇文章添加标签]
  # https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/
  # https://squidfunk.github.io/mkdocs-material/plugins/tags/#meta.tags
  - tags
markdown_extensions:
  # [数学公式支持]
  # https://squidfunk.github.io/mkdocs-material/reference/math/#katex
  - pymdownx.arithmatex:
      generic: true
  # [图片功能支持]
  # https://squidfunk.github.io/mkdocs-material/reference/images/
  # 给 Markdown 图片语法后面添加 `{width="300"}` 设置大小
  - attr_list
  - md_in_html
  # [给标题添加链接]
  # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.permalink
  - toc:
      permalink: true # 固定标题位置为当前位置
  # [代码语法高亮]
  # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-blocks
  # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight
  - pymdownx.highlight:
      # 显示行号
      linenums: true
      # 显示编程语言名称
      auto_title: true
      # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.line_spans
      line_spans: __span
      # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.pygments_lang_class
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  # [Markdown 提示]
  # https://squidfunk.github.io/mkdocs-material/reference/admonitions/
  - admonition
  - pymdownx.details
  # [Markdown footnote 语法支持]
  # https://squidfunk.github.io/mkdocs-material/reference/footnotes/
  - footnotes

extra_javascript:
  # [数学公式支持]
  # https://squidfunk.github.io/mkdocs-material/reference/math/#katex
  - mkdocs/javascripts/katex.js
  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js
  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/contrib/auto-render.min.js
extra_css:
  # [数学公式支持]
  # https://squidfunk.github.io/mkdocs-material/reference/math/#katex
  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.css
  # [自定义 css]
  # 不使用底部的翻页
  - mkdocs/css/no-footer.css
  # 无序列表符号自定义
  - mkdocs/css/unordered-list-symbols.css

command + S保存后，运行mkdocs serve，会遇到报错，但是只要按着报错的提示提示信息进行下载，然后再运行mkdocs serve就可以加载成功

5. 代码美化

6. 添加一些icons或者emojs

7. 与github联动起来

新建一个文件夹.github

在终端中输入

mkdir .github
cd .github
mkdir workflows
cd workflows
vim PublishMySite.yml

name: publish site
on: # 在什么时候触发工作流
  push: # 在从本地main分支被push到GitHub仓库时
    branches:
      - main
  pull_request: # 在main分支合并别人提的pr时
    branches:
      - main
jobs: # 工作流的具体内容
  deploy:
    runs-on: ubuntu-latest # 创建一个新的云端虚拟机 使用最新Ubuntu系统
    steps:
      - uses: actions/checkout@v2 # 先checkout到main分支
      - uses: actions/setup-python@v2 # 再安装Python3和相关环境
        with:
          python-version: 3.x
      - run: pip install mkdocs-material # 使用pip包管理工具安装mkdocs-material
      - run: mkdocs gh-deploy --force # 使用mkdocs-material部署gh-pages分支

提交

返回到根目录后：

git add . # 将当前所有文件纳入管理
git commit -m $'Adding initial documentation files'
git push origin main
mkdocs gh-deploy --clean # 构建本地站点并自动推送到远程gh-pages分支,这条命令会自动生成站点，并创建gh-pages分支（若没有），并推送到远程仓库。

刷新我们仓库，可以看见已经更新成功

部署站点

点击Save

进入到Actions，看到这个地址就是我们的网页了

8. 每次的更新

git init
git add .
git commit -m "update"
git branch -M main
git push -u origin main