使用github 挂载部署自己的静态网站

明白了，你想在 GitHub 上部署自己的笔记，用 MkDocs 来管理文档。下面我给你整理一个完整的流程，包括创建项目、写文档、生成站点、推送到 GitHub Pages。

1️⃣ 安装 MkDocs

先在本地安装 Python 和 pip，然后安装 MkDocs：

pip install mkdocs

如果你想用 Material 主题（推荐）：

pip install mkdocs-material

2️⃣ 初始化 MkDocs 项目

在你本地选择一个目录，例如 my_notes：

mkdir my_notes
cd my_notes
mkdocs new .

生成的目录结构大概如下：

my_notes/
├── docs/
│   └── index.md
├── mkdocs.yml
  • docs/ → 存放 Markdown 文件
  • mkdocs.yml → 配置文件

3️⃣ 编辑文档

在 docs/ 目录下编辑 Markdown 文件，例如：

# index.md

# 我的笔记

欢迎阅读我的笔记！

## 第一章

内容……

你可以创建多个 Markdown 文件：

docs/
├── index.md
├── chapter1.md
├── chapter2.md

然后在 mkdocs.yml 中配置导航：

site_name: 我的笔记
theme:
  name: material

nav:
  - 首页: index.md
  - 第一章: chapter1.md
  - 第二章: chapter2.md

4️⃣ 本地预览

在本地预览效果：

mkdocs serve

浏览器访问：

http://127.0.0.1:8000

看到你的 MkDocs 网站效果。

5️⃣ 生成静态站点

生成静态文件用于部署：

mkdocs build

会在项目根目录生成 site/ 文件夹，里面就是静态网页。

6️⃣ 推送到 GitHub

6.1 创建 GitHub 仓库

  1. 登录 GitHub，创建仓库，例如 my_notes
  2. 克隆仓库到本地：
git clone https://github.com/username/my_notes.git
cd my_notes

6.2 添加 MkDocs 项目文件

把你的 MkDocs 项目内容（mkdocs.yml + docs/ 文件夹）放入仓库目录。

git add .
git commit -m "Add MkDocs notes"
git push origin main

7️⃣ 部署到 GitHub Pages

使用 MkDocs 内置命令一键部署：

mkdocs gh-deploy
  • 第一次运行会创建 gh-pages 分支
  • 每次修改 Markdown 后，再运行 mkdocs gh-deploy 自动更新网页

部署成功后，GitHub Pages 地址一般是：

https://username.github.io/my_notes/

8️⃣ 可选：自定义域名 & HTTPS

  • 在 mkdocs.yml 添加自定义域名：
site_name: 我的笔记
site_url: https://notes.example.com
  • 在 GitHub 仓库设置 → Pages → 添加自定义域名
  • GitHub 会自动启用 HTTPS（免费）

✅ 总结

  1. 安装 MkDocs + Material
  2. 初始化项目 mkdocs new .
  3. 编辑 docs/*.md 和 mkdocs.yml
  4. 本地预览 mkdocs serve
  5. 构建静态网站 mkdocs build
  6. 推送到 GitHub
  7. 部署 mkdocs gh-deploy

换一个主题 Read the Docs.

👌 你想把 MkDocs 主题换成 Read the Docs 风格，操作非常简单。

1️⃣ 修改 mkdocs.yml

在 mkdocs.yml 里，把 theme 改为 readthedocs：

site_name: 我的笔记
theme:
  name: readthedocs

nav:
  - 首页: index.md
  - 第一章: chapter1.md
  - 第二章: chapter2.md

2️⃣ 本地预览

保存后运行：

mkdocs serve

浏览器打开 http://127.0.0.1:8000 就能看到 Read the Docs 风格 的页面。

3️⃣ 重新部署

如果你之前已经用 GitHub Pages 部署，换主题后重新部署一次：

mkdocs gh-deploy

GitHub Pages 就会更新为新的主题。

🔹 补充

  • readthedocs 是 MkDocs 内置主题之一，不需要额外安装。
  • 如果你以后还想尝试更多主题，可以去官方主题库看（Material、Cinder、MkDocs Bootstrap 等）。

只需要mkdocs gh-deploy 不需要push吗

好问题 👍

在 MkDocs + GitHub Pages 的工作流里：

📌 两种情况

1. 只改了文档（Markdown 文件）

  • 运行 mkdocs gh-deploy 就够了。

  • 它会自动：

    1. 构建 site/ 静态页面
    2. 创建/更新 gh-pages 分支
    3. 推送到远程仓库

👉 所以这种情况下你不需要再手动 git push。

2. 改了配置（mkdocs.yml、CNAME、requirements.txt 等）或源文件

  • 这些文件也需要版本管理（放在 main 分支）。
  • 需要先 git add . && git commit -m "update config" 然后 git push，
    这样以后你换电脑、或者别人也能直接拉到最新配置。

✅ 总结

  • 只想更新站点内容 → mkdocs gh-deploy 就行
  • 想同步源码和配置 → 还需要 git push

如果无法更新还是最好 push 一下

git add .
git commit -m "Add MkDocs notes"
git push origin main

使用git ci流程自动部署

✅ 你说的就是让 GitHub 每次 push 后自动构建 MkDocs 并发布到 GitHub Pages。这个用 GitHub Actions 就可以实现。

下面我给你一个完整的配置方案：

1️⃣ 打开 GitHub Pages

  1. 打开仓库 → Settings → Pages
  2. Source 选择 GitHub Actions
    （新版本 GitHub Pages 默认支持 Actions）

2️⃣ 添加 GitHub Actions 工作流

在你的仓库根目录下新建：

.github/workflows/gh-pages.yml

内容如下：

name: Deploy MkDocs site to GitHub Pages

on:
  push:
    branches:
      - main   # 或者 master，看你仓库的主分支

permissions:
  contents: write

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'

      - name: Install MkDocs and plugins
        run: |
          pip install mkdocs
          pip install mkdocs-material  # 如果用 material 主题
          # pip install mkdocs-xxx      # 其他插件可加在这里

      - name: Build and Deploy
        run: mkdocs gh-deploy --force

3️⃣ 工作流程说明

  • 触发条件：每次推送到 main 分支时运行

  • 步骤：

    1. 拉取代码
    2. 安装 Python & MkDocs
    3. 运行 mkdocs gh-deploy --force

  • 最终结果：自动把生成的 site/ 部署到 gh-pages 分支，GitHub Pages 就会更新

4️⃣ 自定义域名（可选）

如果你有自定义域名，需要在 mkdocs.yml 里添加：

site_url: https://yourdomain.com

并在 docs/ 下放一个 CNAME 文件，里面写你的域名。
Actions 会自动把它部署到 gh-pages 分支。

✅ 这样你以后只需要：

git add .
git commit -m "update docs"
git push

GitHub 就会自动帮你构建和发布 MkDocs 站点，完全不需要再本地执行 mkdocs gh-deploy。

posted @ 2025-09-04 21:52  学不会xuebuhui  阅读(155)  评论(0)    收藏  举报
Language: javascript //图片预览