diff --git a/docs/tech/Install-Material-for-MkDocs.md b/docs/tech/Install-Material-for-MkDocs.md new file mode 100644 index 0000000..dbd29d7 --- /dev/null +++ b/docs/tech/Install-Material-for-MkDocs.md @@ -0,0 +1,150 @@ +# 安装和配置 Material for MkDocs + +## 安装 + +以下内容基于 Ubuntu 24.04 完成。 + +我们将通过创建一个 Python 虚拟环境以安装 Material for MkDocs。 + +```bash +sudo apt -y install python3 python3-full python3-pip python3.12-venv + +python3 -m venv + +/pip install --upgrade pip setuptools + +/pip install mkdocs-material +``` + +!!! warning "注意" + + 以上命令中的 `` 请替换为 MkDocs 安装目录的绝对路径。 + +这将自动安装所有依赖项的兼容版本: MkDocs、Markdown、Pygments 和 Python Markdown 扩展。 + +## 配置 + +### 新建站点 + +安装 Material for MkDocs 后,就可以使用 mkdocs 命令新建站点。 + +切换到你希望项目所在的目录,然后输入: + +```bash +/mkdocs new . +``` + +### 配置站点 + +在 `mkdocs.yml` 中修改你的站点配置。 + +下面提供我的配置文件,供大家参考: + +```yaml title="mkdocs.yml" +site_name: "Cat Tom's Blog" # 站点名称 +site_url: https://blog.cattom.site # 站点链接 +site_author: Cat Tom # 作者 +# 代码仓库信息 +repo_name: cattom/blog +repo_url: http://cattomserver3-1.tail184fc.ts.net:84/cattom/blog.git +# 版权信息 +copyright: Copyright © 2024 | Cat Tom + +theme: + name: material + language: zh + logo: https://static.cattom.site/image/icon/40.png + favicon: https://static.cattom.site/image/icon/favicon-32x32.png + features: + - navigation.tabs + - navigation.instant + - navigation.instant.prefetch + - navigation.tracking + - navigation.top + - navigation.indexes + - search.suggest + - search.highlight + - content.code.copy + - content.code.annotate + - content.tabs.link + palette: + primary: blue grey + accent: light blue + +markdown_extensions: + # Python Markdown + - abbr + - tables + - admonition + - attr_list + - def_list + - footnotes + - md_in_html + - toc: + permalink: true + # Python Markdown Extensions + - pymdownx.critic + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.snippets + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + +nav: + - "主页": index.md + - "生活": + - life/index.md + - "原发免疫性血小板减少症 (ITP)": life/ITP.md + - "技术": + - tech/index.md + - "Mi 6 (sagit)": tech/Mi6(sagit).md + - "极1S (HC5661)": tech/HC5661.md + - "Git: 覆盖本地修改": tech/Git-overwriting-local-changes.md + - "Redmi 4X (santoni)": tech/Redmi4X(santoni).md + - "手把手教你备份和还原 Docker 卷": tech/Backup-and-Restore-of-Docker-Volumes-A-Step-by-Step-Guide.md + - "在 Ubuntu 24.04 上添加交换空间": tech/How-to-Add-Swap-Space-on-Ubuntu-2404.md + - "Docker Compose: 限制容器的资源使用": tech/Docker-Compose-Limiting-container-resource-usage.md + - "创建和管理 Linux 服务器用于身份验证的 SSH 密钥": tech/Creating-and-Managing-SSH-Keys-for-Authentication-on-Linux-Servers.md + - "将已经失效的 Onedrive 账户从资源管理器边侧栏去除": tech/Remove-deactivated-Onedrive-accounts-from-Explorer-sidebar.md + - "MkDocs 参考": examples/index.md + +plugins: + - search + - glightbox + +``` + +### 生成静态网页 + +编辑完成后,您可以使用 Markdown 文件构建静态网站: + +```bash +/mkdocs build +``` + +这将会在你的项目目录中生成 `site` 文件夹,里面包含了站点的所有静态文件。 + +你可以将 `site` 文件夹上传至云服务器或者 S3 存储以向公开你的站点。当然,你也可以参考[官方文档](https://squidfunk.github.io/mkdocs-material/publishing-your-site/),利用 Github Pages 托管你的网站。 \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 3689ef8..de80af7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -83,6 +83,7 @@ nav: - "Redmi 4X (santoni)": tech/Redmi4X(santoni).md - "手把手教你备份和还原 Docker 卷": tech/Backup-and-Restore-of-Docker-Volumes-A-Step-by-Step-Guide.md - "在 Ubuntu 24.04 上添加交换空间": tech/How-to-Add-Swap-Space-on-Ubuntu-2404.md + - "安装和配置 Material for MkDocs": tech/Install-Material-for-MkDocs.md - "Docker Compose: 限制容器的资源使用": tech/Docker-Compose-Limiting-container-resource-usage.md - "创建和管理 Linux 服务器用于身份验证的 SSH 密钥": tech/Creating-and-Managing-SSH-Keys-for-Authentication-on-Linux-Servers.md - "将已经失效的 Onedrive 账户从资源管理器边侧栏去除": tech/Remove-deactivated-Onedrive-accounts-from-Explorer-sidebar.md