Skip to content

Latest commit

 

History

History
167 lines (124 loc) · 5.07 KB

README-CN.md

File metadata and controls

167 lines (124 loc) · 5.07 KB
title tags
利用Mkdocs部署静态网页至GitHubpages
Mkdocs

!!! info 官方网站：MkDocs{target=“_blank”}

我的个人网站成果：<http://wcowin.work/>{target=“_blank”}

一、准备工作(重要)

1.下载Github Desktop{target=“_blank”}

2.有一个GitHub账号​​​​​​​

3.打开电脑终端安装mkdocs: pip install mkdocs-material

二、Creating your site

参考教程：

利用mkdocs部署静态网页至GitHubpages（更新版）{target=“_blank”}

与其他教程不同，我首先建议先在Github创建一个名为你的名字+github.io的仓库(不是这个名字的仓库也可以，你需要类比一下) img img

然后打开github Desktop 克隆到本地 img img img img 打开Wcowin.github.io目录进入终端运行:

mkdocs new mkdocs-site

出现下图的几个文件 img

docs文件下是以后网站的内容，mkdocs.yml是配置文件（配置主题，目录，插件等）

你在这个目录下写的任何东西都可以通过github Desktop 上传到github上

以VScode为例我们打开具体看看里面的东西

(必须先执行下面的代码添加一个GitHub Workflow)

mkdir .github
cd .github
mkdir workflows
cd workflows
vim PublishMySite.yml

在PublishMySite.yml里面输入以下内容

name: publish site
on: # 在什么时候触发工作流
  push: # 在从本地main分支被push到GitHub仓库时
    branches:
      - main
  pull_request: # 在main分支合并别人提的pr时
    branches:
      - main
jobs: # 工作流的具体内容
  deploy:
    runs-on: ubuntu-latest # 创建一个新的云端虚拟机 使用最新Ubuntu系统
    steps:
      - uses: actions/checkout@v2 # 先checkout到main分支
      - uses: actions/setup-python@v2 # 再安装Python3和相关环境
        with:
          python-version: 3.x
      - run: pip install mkdocs-material # 使用pip包管理工具安装mkdocs-material
      - run: mkdocs gh-deploy --force # 使用mkdocs-material部署gh-pages分支

!!!重点来了 仓库setings/Actions/General 勾选这两项

目录树状图:

$ tree -a
.
├── .github
│   ├── .DS_Store
│   └── workflows
│       └── PublishMySite.yml
├── docs
│   └── index.md
└── mkdocs.yml

三、配置完善

打开终端运行

pip install mkdocs-material

打开mkdocs.yml

把以下的内容输入进去（最简单配置）

site_name: 网站名字

site_url: 网站链接

site_author: 你的名字

theme:
  name: material #主题

详细mkdocs.yml配置见Changing the colors - Material for MkDocs

下次我会具体谈谈这个问题

在下方终端运行可以在浏览器看到实时网站

mkdocs serve

img img

这个网站就算是初步建好了

最后去github Desktop上传到github img

!!!重点来了 去setings/pages 选择下图示意的路径

你的网站网址就是：​

https://你github的名字.github.io/  （根据仓库名改变）

img

快速开始

打开终端安装mkdocs: pip install mkdocs-material，在你第二步克隆到本地的文件夹下(比如我的就是Wcowin.github.io这个文件夹)的终端执行git clone [email protected]:Wcowin/Mkdocs-Wcowin.git克隆本模版,把Mkdocs-Wcowin文件里的文件复制出来到Wcowin.github.io文件里，随后在Wcowin.github.io文件目录终端里mkdocs serve即可

为了测试随手建的名为1的文件夹

完美运行！

浏览器进入http://127.0.0.1:8000/{target=“_blank”}即可看到端口网页效果

下次谈谈网站的mkdocs.yml具体配置