跳转至

mkdocs

参考教程

  1. MkDocs中文文档
  2. 中文配置material主题
  3. 中文实践
  4. Mkdocs 配置和使用

第一个mkdocs项目

安装MkDocs，系统上需要安装python以及包管理器pip。

Bash
#安装mkdocs
pip install mkdocs
#mkdocs创建第一个文件
mkdocs new blog
cd blog
# 实时编译，用于在本地先写博客调试
mkdocs serve
# 文件目录
- blog
  - mkdocs.yml
  - docs
    - index.md
# 打包编译成网页在/site文件夹中
mkdocs build

上传到github-pages

  1. 在github上创建一个新仓库，设置为 public ,关联本地博客仓库。
  2. 配置远程仓库settings中的pages界面，build and deployment处设置为 branch:gh-pages, /root ，保存。

  3. 两种方案：

  4. 在本地直接执行 mkdocs gh-deploy --clean

  5. 配置github-actions中的workflow，创建新的工作流，存储在.github/workflows/autoPublish.yml中，具体内容如下：

    YAML
    name: autoPublish
on:
  push:
    branches:
      - master
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v2
        with:
          python-version: 3.x

      - run: pip3 install -U -r requirements.txt
      - run: mkdocs gh-deploy --force

mkdoc.yml文件

具体请参考 我的这个博客仓库的mkdoc.yml

基本配置

site，repo相关用来配置网站内容和链接github仓库。

theme，md-extensions，plugins等

选用material主题，排版简洁，左右各有目录，便于阅读。格式大致如下：

YAML
theme:
  name: material
  font: #字体
  icon: #github
    repo: fontawesome/brands/github
  custom_dir: overrides # # 在该文件夹下修改部分配置，覆盖父主题
  features: #设定整体布局特性
  palette: #阅读模式，白天或黑夜

markdown_extensions: #推荐配置Markdown基本语法及其扩展
extra_javascript: #为md文件显示在网页端提供一些必要的js或css文件。
extra: #其他，譬如配置页脚，数据分析。
plugins: #插件，譬如添加搜索栏，关联github最后更新时间。

设置左侧目录：描述以及对应的markdown文件。

YAML
nav:
  - 前言: "index.md"
  - 代码规范: "代码规范/代码规范.md"
  - 实用工具:
      - 科学上网: "tools/科学上网.md"

giscus配置博客评论系统

如何使用 GitHub 讨论作为您博客的聊天系统_杭州程序员张张的博客-CSDN博客_github上如何私信

gitcus是一个由Github Discussion支持的评论系统。它可以让你把仓库中的讨论整合到你的博客中。 读者在博客上留下评论，这些评论会同时出现在你的代码库的讨论区中。

  1. 首先设置仓库是 public 的，并开启 discussion 权限（在repo的settings中进行设置）。

  2. 安装 giscus应用程序。并对选定的代码库开启权限。

  3. 进入 giscus主界面，选定语言，仓库，映射关系（选择URL或者title），Discussion分类，特性（一般选择启用主帖子上的反应，评论框放在评论上方，懒加载评论），主题。 然后 复制下面的html代码。

  4. 在mkdoc.yml文件的custom_dir变量配置了用于覆盖原配置的文件夹，eg：我设置了custom_dir:overrides，因此在overrides文件夹下新建main.html文件。在main.html文件中一定要设置{% extends "base.html %"}。 下面是我的main.html文件。

HTML
{% extends "base.html" %} 
{% block giscus %}
<script src="https://giscus.app/client.js" data-repo="Emma-ssq/blog" data-repo-id="R_kgDOIAA20A"
        data-category="Announcements" data-category-id="DIC_kwDOIAA20M4CRiD-" data-mapping="title" data-strict="0"
        data-reactions-enabled="1" data-emit-metadata="0" data-input-position="top" data-theme="light" data-lang="zh-CN"
        data-loading="lazy" crossorigin="anonymous" async>
        </script>
{% endblock %}
最后更新: September 22, 2022
Back to top