官网地址: https://squidfunk.github.io/mkdocs-material/
参考文档:
https://cyent.github.io/markdown-with-mkdocs-material/
https://zhuanlan.zhihu.com/p/613038183

Q: mkdocs和material是什么？
A: mkdocs: 可以用于生成静态文档网站..不需要安装node.js,与gitbook、hexo相比,搭建过程更加简便!!
       material: material是mkdocs的主题之一. 我觉得还不错.

有一个弊端,mkdocs是支持 热更新 的,文档一多,一旦修改下,会全部重新加载... 我直接裂开.
它要是能只重新加载修改的文件该多好.. ╮(￣▽￣"")╭

Ps: 我还发现了一个博客搭建平台,有超多好看的模版 https://halo.run/

Mkdown格式

为了让文档内容和目录看起来更美观, 我会这样做

○ 换行用硬换行 两下空格+shift+enter
○ mkdown会将多个空格识别为一个空格, So, 使用多个  进行缩进
   若是mac玩家,可以在 系统偏好设置-键盘-文本里 进行快捷设置
(eg: 设置后键盘输入 aa 就会提示 4个  , 再按空格输入成功)
○ ##二级目录
### <font color='orange'>三级目录</font>
##### <font color='purple' size=4>五级目录</font>
○ ** ** 左右按一下空格,*号包裹的内容要与*紧贴, 但与外面内容接触时中间要有个空格
○ 切记代码块里用连续多个空格,不要用tab键..

---

搭建

安装依赖,创建项目

pip3 install mkdocs-material
python3 -m mkdocs new Dc_IT (Dc_IT是我的项目名)

文档树结构如下:

.
├── docs
│   ├── 2_python面向过程  # -- 可以在docs下创建新文件夹,在该文件夹下放置mkdown文档
│   ├── index.md  # -- 首页
│   ├── readme.md
│   ├── resources # -- 我用来存放logo、css的
│   │       ├── css
│   │       │    └── extra.css
│   │       └── images
│   └── favicon.ico
│   └── tips  # -- 我新创建的另外的一个目录
└── mkdocs.yml

注意:
        重新打开网站, 呈现的是 index.md 的内容, 哪怕你没有将它夹到nav中..
        navigation的配置最好放到前面, 放后面有时候不生效..折腾了我半天..╮(￣▽￣"")╭

配置文件

mkdocs.yml 配置文件说明. 参考博客: https://blog.csdn.net/m0_63203517/article/details/129765689

mkdocs.yml里添加:

site_name: IT之旅
site_description: These are my study notes.
site_author: DC
copyright:  Copyright © 2022 from Dc_OnePiece
extra:
  generator: false

# -- 在网站上输入http://127.0.0.1:8000/就已经定位到了docs文件夹下
# -- navs里第一层(Tips、Python面向对象)是导航栏标签;第二层对应每个导航下左侧的目录
nav:
  - Tips:
    - mkdocs-material的搭建: tips/mkdocs-material.md
  - python面向对象:
    - 数据类型:
        - python语言介绍: 2_python面向过程/00_python语言介绍.md
        - 基本运算符和流程控制: 2_python面向过程/01_基本运算符和流程控制.md
        - 数据类型之序列: 2_python面向过程/02_数据类型之序列.md
        - 数据类型之哈希: 2_python面向过程/03_数据类型之哈希.md
    - 函数:
        - 函数基础: 2_python面向过程/04_函数基础.md
        - 函数高级: 2_python面向过程/05_函数高级.md
        - 函数进阶: 2_python面向过程/06_函数进阶.md
  - Me: 
    - About Me: ./readme.md

theme:
  name: 'material'      # 主题
  features:
    - navigation.tabs   # 导航标签 注意,不是tabs:true
    - navigation.top    # 回到顶部
    - navigation.expand # 默认打开左侧导航所有小节
    # - navigation.instant
    # - navigation.tracking
    # - navigation.tabs.sticky
    # - navigation.sections
    # - navigation.indexes
    # - toc.integrate
    # - header.autohide
  palette:
    primary: "blue grey"
    accent: 'amber'
  custom_dir: docs/resources/ # 额外的配置(eg:logo css)
  favicon: resources/images/favicon.ico
  logo: resources/images/favicon.ico
  language: 'zh'
  # font:
  #   code: Roboto Mono


extra_css:
  - resources/css/extra.css  # 修改css默认的样式


markdown_extensions:
  # Python Markdown
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - toc:
      permalink: true
  # Python Markdown Extensions
  - 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.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

extra.css里添加: 这是按照我自个儿的想法来的

/* 整体内容占据宽度 */
.md-grid {
    max-width: 64rem;
}

/* 隐藏页脚 */
/* .md-footer-meta__inner {
    display: none;
} */

/* 改变当前选中目录的颜色 */
.md-nav__item .md-nav__link--active {
    color: #ea8685;
}

/* 更改h1标签内容的颜色 */
.md-typeset h1 {
    /* color: #718093; */
    /* color: #01a3a4; */
    color: #ea8685;
}

/* 更改导航栏的背景颜色 */
[data-md-color-primary=blue-grey] {
    --md-primary-fg-color: #718093;
}

/* 更改右侧 目录一丢丢排版的间距 */
.md-sidebar--secondary .md-nav {
    padding-left: 0.8rem;
}

/* 试着添加背景图片 效果不佳. 还是以简约为主吧Hhh */
/* .md-main {
    background-image: url("../images/bac.jpg");
    background-repeat: no-repeat;
    background-attachment: fixed;
    background-position: right bottom;
    opacity: 0.7;
} */

启动网站

python3 -m mkdocs serve cd到项目路径下,要保证该路径下有mkdocs.yml文件

---

部署

弄好后,可以部署到gitee page或github page上!

1> mkdocs的yml文件的配置
   https://wcowin.work/blog/Mkdocs/mkdocs2/
2> 运行 python3 -m mkdocs serve 看看效果
3> 配置同时使用 Gitlab、Github、Gitee(码云) 共存的开发环境
   https://www.jianshu.com/p/68578d52470c
   注: 
      1> 先清除在电脑里已有的私钥和公钥 
      2>一定要ssh-add!! 
      3>设置Port 443,修改后修改后,在本地add commit后.执行mkdocs gh-deploy.会快很多!!!
        （指定gh-deploy之前,有site先删除site文件夹!!放心,该命令会重新生成的!）
   ssh-keygen -t rsa -f ~/.ssh/id_rsa.github -C "[email protected]"
   ssh-keygen -t rsa -f ~/.ssh/id_rsa.gitee -C "[email protected]"
4> 我们现在是如何部署的呢?
   - 先在github上创建一个跟docs目录的上级目录一样的项目,便于管理!(创建时,公开、勾选自动创建readme文件)
   - 在本地运行感觉没问题后. 进入该目录下. 
     git init    git status 
     git add .
     git commit -m ".."     git status 
     git remote add origin 刚在github上创建的项目的ssh的远程地址
     (还很奇怪,名称要命名为origin..不然不成功; So,现在要部署另外一个项目时,该origin对应的远程地址也得变一下.)
   - 在有mkdocs.yml的目录下,运行命令  mkdocs gh-deploy
     (不出意外,本地会多个site文件夹,远程会多个gh-deploy分支,并且里面是site文件夹里的内容!!)
   - 然后进入github中,选择项目的gh-deploy分支,点击项目的settings,在左侧找到Pages!!
     它会说 Your site is live at https://onepiecedc.github.io/项目名/
5> 如何更新的呢?
   现目前我是,修改后,在本地add commit后.执行mkdocs gh-deploy.
   (其实我想试一试,mkdocs bulid后,将其内容传到项目已有的gh-deploy分支,不晓得行不行?!)

其他的
下次可以试试不传docs目录和site,
(看了下,好像不将docs和site写到.gitignore文件也没关系,它是这么一回事:
 mkdocs gh-deploy仅仅会在远程创建分支,并把生成的静态资源传进去.
 而我们在本地执行python3 -m mkdocs bulid后,出现的site目录下就是生成的静态资源!!)
https://www.cnblogs.com/paulwhw/p/12725523.html


To do:
GitHub+Travis+Mkdocs自动化构建文档库
https://cloud.tencent.com/developer/article/1644675
另外的:  
https://cloud.tencent.com/developer/article/1935771

---

我现在认为 cloudflare page是 静态网页访问最稳定最快速 部署最方便的方案!!（国内不用梯子也可以很流畅的访问

---