1.利用Mkdocs部署静态网页
💾 AI智能摘要 (DeepSeek)
本文介绍了使用MkDocs部署静态网页到GitHub Pages的完整流程。重点讲解了从创建GitHub仓库、本地环境配置、MkDocs初始化到自动化部署的关键步骤,包括目录结构调整、workflow配置和页面发布设置。该方法基于Material for MkDocs主题,通过简单的YAML配置即可快速搭建文档网站,适合技术博客和项目文档的托管需求。文中提供了详细的图文指引和常见配置示例,并强调了GitHub Actions自动化部署的关键设置要点。
📖 阅读信息
阅读时间:1 分钟 | 中文字符:485 | 有效代码行数:75
Info
Material for MkDocs官方网站: Material for MkDocs
MkDocs中文文档: MkDocs中文文档
推荐看下这个视频:
How to set up Material for MkDocs by @Wcowin –
10m – 用MKdocs构建一个博客网站.
一、准备工作¶
1.下载Github Desktop
2.有一个GitHub账号(有手就行)
二、Creating your site¶
参考教程:
利用mkdocs部署静态网页至GitHubpages(更新版)
与其他教程不同,我首先建议先在Github创建一个名为你的名字+github.io的仓库
然后打开github Desktop 克隆到本地
打开Wcowin.github.io目录进入终端依次运行:
出现下图的几个文件
Tip
这里建议把mkdocs-site文件里的东西全部剪切出来到Wcowin.github.io文件里
Wcowin.github.io是克隆到本地的仓库(里面包含docs,yml文件等等),docs文件下是以后网站的内容,mkdocs.yml是配置文件(配置主题,目录,插件等)
你在这个目录下写的任何东西都可以通过Github Desktop 上传到github上
执行下面的代码添加一个GitHub Workflow
过时的PublishMySite.yml
(执行下面的代码添加一个GitHub Workflow(已经过时但是仍然能用,最新方法见下方ci.yml)
在PublishMySite.yml里面输入以下内容
进入.github/workflows/ci.yml,然后复制并粘贴以下内容:
到这里先检查一下你的目录结构
目录树状图:
重点来了
Github仓库setings/Actions/General 勾选这两项
三、配置完善¶
打开mkdocs.yml
把以下的内容输入进去(最简单最基础的配置)
详细mkdocs.yml配置见Changing the colors - Material for MkDocs
下次我会具体谈谈这个问题
在下方终端运行可以在浏览器看到实时网站


这个网站就算是初步建好了
最后去github Desktop上传到github
上图可以看到,我上传了Wcowin.github.io文件夹,这个文件夹里面包含了mkdocs.yml和docs文件夹(mkdocs-site文件夹现在没有东西,可以删除)
!!!重点
去仓库的setings/pages选择下图示意的路径
等待一会网址就出来了1
你的网站网址就是:

下次谈谈网站的mkdocs.yml具体配置
四、参考资料¶
-
于2025.2.19重写此文 ↩