发布网站

一、安装：

在cmd中执行

1
pip install mkdocs

和

1
pip install mkdocs-material

二、创建

在D盘中输入

1
mkdocs new myproject

这里的myproject是你的文件夹名字(下面都用my-wiki代替)

mkdocs.yml是你的你的配置文件，在里面修改好之后，cd my-wiki
输入

1
mkdocs serve

会跳出：

这个网址点进去之后可以本地预览

三、更改主题：

在mkdocs.yml里输入：

1
2
3
4
site_name: My site
site_url: https://mydomain.org/mysite
theme:
  name: material

再重新serve即可

四、部署

在github上创建仓库，权限设为public，然后依次

1
2
3
4
5
6
git init
git add .
git commit -m"..."
git remote add origin https://github.com/Hamilton2718/GYYZ-ZJU.git
git branch -M main
git push -u origin main

然后在仓库里的settings->page把分支改为gh-pages，如下：加载失败
之后输入

1
mkdocs gh-deploy

点击它给你的网站就行了

五、problems

1. 如果遇到fatal: unable to access 'https://github.com/Hamilton2718/GYYZ-ZJU.git/': Recv failure: Connection was reset的报错输入

1
2
git config --global --unset http.proxy 
git config --global --unset https.proxy

操作

一、多级目录

我们也可以根据需要生成多级目录，多级目录也要在 mkdocs.yml 中配置。多级目录的语法格式如下：

1
2
3
- [一级目录名称]:
    - [子目录名称]:[文件路径/文件名.md]
    ...

注意： 其中 [子目录名称] 可以省略，如果省略，那么当前页面名称即显示为该 markdown 文件的一级标题。实例：

1
2
3
4
5
6
7
8
nav:
- Home: index.md
- User Guide:
    - Writing your docs: user-guide/writing-your-docs.md
    - Styling your docs: user-guide/styling-your-docs.md
- About:
    - License: about/license.md
    - Release Notes: about/release-notes.md

二、插入图片

将图片放在和md文件一个目录下的img文件夹，如图：加载错误
插入时直接从\img开始写相对路径

1
![加载错误](img/image.png)

注意要用/不要用\，和mkdocs不一样

三、更改设置

建议直接在yml文件中参考地加入这些：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
site_name: GYYZ-ZJU

site_url: https://mydomain.org/mysite

nav:
- 首页: index.md
- 衣食住行:
    - 杭州旅游攻略: FCHT/杭州旅游攻略.md

- 奇怪的知识又增加了:
    - mkdocs教程: other/mkdocs.md
    - test: other/Markdown实例.md

theme:
  name: material

  favicon: images/fav.jpg

  icon:
   logo: material/home

  features:
    - navigation.instant   #- header.autohide  #自动隐藏
    #- announce.dismiss   #呈现可标记为由用户读取的临时公告，可以包含一个用于取消当前公告的按钮
    - navigation.tracking   #地址栏中的 URL 将自动更新为在目录中突出显示的活动锚点
    - navigation.tabs   #顶级部分将呈现在上面视口标题下方的菜单层中，但在移动设备上保持原样
    - navigation.tabs.sticky    #启用粘性选项卡后，导航选项卡将锁定在标题下方，并在向下滚动时始终保持可见
    - navigation.sections   #启用部分后，顶级部分在边栏中呈现为1220px以上视口的组，但在移动设备上保持原样
    - navigation.top   # 返回顶部的按钮 在上滑时出现
    - search.suggest   # 搜索输入一些字母时推荐补全整个单词
    - search.highlight   # 搜索出的文章关键词加入高亮
    - navigation.expand   # 打开Tab时左侧目录全部展开
    #- navigation.indexes   #启用节索引页后，可以将文档直接附加到节
    - search.share   #搜索分享按钮
    - toc.follow # 滚动的时候侧边栏自动跟随
    - navigation.footer # 页脚提示下一章
    - content.code.copy # 代码段上的赋值按钮
    
  palette:
# 切换到亮色
    - media: "(prefers-color-scheme: light)" # 根据系统的颜色模式自动切换
      scheme: default
      primary: blue
      accent: blue
      toggle:
          icon: material/weather-night
          name: 切换到暗色模式

    # 切换到暗色
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: blue
      accent: blue
      toggle:
          icon: material/weather-sunny
          name: 切换到亮色模式

markdown_extensions:
    - admonition # 警告语法
    - def_list
    - footnotes
    - abbr
    - pymdownx.caret
    - pymdownx.mark
    - pymdownx.tilde
    - md_in_html
    - pymdownx.arithmatex: # latex支持
          generic: true
    - toc:
          permalink: true # 固定标题位置为当前位置
          toc_depth: 3 # 目录深度
    - pymdownx.highlight: # 代码块高亮
          anchor_linenums: true
          linenums: true # 显示行号
          use_pygments: true # 代码高亮
          pygments_lang_class: true
          auto_title: true # 显示编程语言名称
          linenums_style: pymdownx-inline # 行号样式,防止复制的时候复制行号
    - pymdownx.betterem # 强调美化,比如**text**会被美化
    - pymdownx.caret # 上标和下标
    - pymdownx.mark # 上标和下标
    - pymdownx.tilde # 上标和下标
    - pymdownx.keys # 显示按键组合
    - pymdownx.critic
    - pymdownx.details # 可以折叠的代码块 ??? note 可以让警告变成折叠的
    - pymdownx.inlinehilite
    - pymdownx.snippets
    - pymdownx.superfences
    - pymdownx.magiclink # 自动识别链接
    - pymdownx.smartsymbols # 智能符号
    - pymdownx.snippets # 代码段
    - pymdownx.tasklist:
          custom_checkbox: true # 自定义复选框
    - attr_list
    - pymdownx.emoji:
          emoji_index: !!python/name:material.extensions.emoji.twemoji
          emoji_generator: !!python/name:material.extensions.emoji.to_svg
    - pymdownx.superfences: # 代码块中支持Mermaid
          custom_fences: # 支持 Mermaid
              - name: mermaid
                class: mermaid
                format: !!python/name:pymdownx.superfences.fence_code_format
    - pymdownx.tabbed:
          alternate_style: true
          combine_header_slug: true
    - pymdownx.tasklist:
          custom_checkbox: true
          clickable_checkbox: true
    - meta # 支持Markdown文件上方自定义标题标签等
    - tables

extra_css:
  - stylesheets/extra.css