使用Github Pages结合MkDocs制作个人网站

目录

环境配置

创建网页仓库

创建Github仓库

创建本地仓库

本地运行网页

配置主题

网站部署到Github

docs文件夹介绍

修改主页显示内容

添加新文件

mkdocs.yml文件介绍

其他效果


环境配置

为了正确的安装Mkdocs,需要先下载Python环境

下载地址:Welcome to Python.org

下载完毕后输入下面的指令安装MkDocs

复制代码
 pip install mkdocs

为了使网页更加精美,可以安装Materia For MkDocs,使用下面的指令进行安装

复制代码
 pip install mkdocs-material

创建网页仓库

首先进入Github,对于Github Pages来说,一共有两种网站:

  1. 个人网站:仓库名为<username>.github.io,<username>为当前账户的名字,不可以为其他名字,后面内容github.io是固定的不可以修改,一个账户只可以创建一个

  2. 仓库网站:仓库名随意,一个账户可以创建多个

本次教程以仓库网站为例

创建Github仓库

作为网页的仓库必须为公开,不可以私有

创建本地仓库

使用git将Github的仓库克隆到本地

复制代码
 git clone 远程仓库地址

克隆完成后进入该目录,在该目录下使用命令行工具打开,输入下面的指令

复制代码
 mkdocs new 网站项目名称

创建成功后可以看到两个默认文件

在docs文件夹中有一个index.md,这个文件

复制代码
 mkdocs build 

是主页文件,当直接进入页面时会优先加载这个markdown文件,以后要展示在网页的文档也写在docs文件夹中,第二个文件mkdocs.yml是mkdocs的配置文件,用于一些功能的配置

本地运行网页

创建完成网页文件后,进入网页项目目录,输入下面的指令在本地构建网页

复制代码
 mkdocs build 

构建完成后输入下面的指令运行本地服务器

复制代码
 mkdocs serve

下面的http://127.0.0.1:8000/就是本地服务器运行的网址,在浏览器地址栏中粘贴该网址即可访问网站

在命令行使用Ctrl+C结束服务器的运行

配置主题

前面已经安装了主题文件,接下来需要在mkdocs.yml文件中配置主题

复制代码
 theme:
     name: 'material'

配置成功后重新构建运行后如下图所示:

网站部署到Github

将刚才创建的文件push到Github,再执行下面的命令进行部署

复制代码
 mkdocs gh-deploy

结果如下:

https://H0308.github.io/Personal_Website/即为云端服务器网址,只要复制到地址栏即可访问

docs文件夹介绍

修改主页显示内容

docs文件夹主要放置用于显示在网页中的md文件,如果想要修改主页文件,可以对index.md进行修改,例如将网页内容修改为:Welcome to my wiki

保存index.md文件,将index.md文件上传到云端后重新进行一次部署,部署后将修改过的文件再一次进行部署,最后上传到云端,刷新网页就可以看到修改后的网页

添加新文件

直接在docs文件夹下新建一个新的md文件,通过与更新index.md文件同样的步骤即可完成网页新增文件,例如直接创建一个blogs.md文件

部署完成后在网页中即可看到新建的md文件,文档的文件名会被默认当做标题,如果文件中有1级标题,则该标题作为文件名

mkdocs.yml文件介绍

mkdocs.yml文件是mkdocs的配置文件,默认情况下会有一个site_name,该属性的值是网站的标题,

修改site_name前效果如下:

修改site_name:

修改mkdocs.yml文件后需要重新构建网站,构建后才能进行部署

部署成功后效果如下:

其他效果

可以参考下面的网站进行相关修改:

MkDocs文档:

MkDocs 中文文档 (markdown-docs-zh.readthedocs.io)

MkDocs开发文档(设置多级目录时需要使用):

简介 - MkDocs 文档开发教程 (mkdocs-like-code.readthedocs.io)

Material主题文档:

Material for MkDocs - Material for MkDocs 中文文档 (llango.com)

相关推荐
TunerT_TQ37 分钟前
【开源评测】google-labs-code/stitch-skills:从设计交接到可检查的组件产物
github
一条Go2 小时前
探测规则:为什么它是告警规则的一种,而不是独立的任务体系
后端·架构·github
一条Go2 小时前
开源新生代雷达 · 第 17 期
github
怕浪猫2 小时前
2026 GitHub 最火的 10 个视频制作与剪辑开源项目:AI 出片、代码生视频、无损剪辑怎么选(附实测截图)
github
dong_junshuai20 小时前
每天一个开源项目#162 NGINX:流式响应背后的缓冲、背压与重试
github
测试员周周20 小时前
【agent评测】:真实系统演示工具调用长什么样,用例怎么设计,怎么测
前端·后端·github
吴长建先生重名了21 小时前
Laravel 项目中使用 Eloquent 实现 IM
github
网易云信1 天前
三折叠 IM 怎么适配?云信鸿蒙 UIKit 的分栏、导航与状态保留实践
github
guuguo1 天前
【做个开源软件】Mac 上 node 进程莫名吃掉 6G 内存?给 AI / MCP 做了个深度归因和安全回收工具
人工智能·开源·github
一条Go1 天前
源新生代雷达 · 第 16 期
github