利用 github action 生成 docsify 的文件目录

前言

docsify 可以快速帮你生成文档网站。不同于 GitBook、Hexo 的地方是它不会生成静态的 .html 文件，所有转换工作都是在运行时。

根据 docsify 官网的快速开始可以很快地就搭建一个个人博客。 搭配 github pages 就可以拥有一个公网可访问的静态博客。

网上关于如何使用docsify和github pages的文章网上已经有挺多的了，这里就不做详细介绍。这里主要是介绍如何使用github action来生成文件目录。因为docsify本身是一个静态网页，只需要生成一次index.html就可以运行，所以本身是不支持动态去显示文件目录。但是docsify支持自定义侧边栏，只需要在根目录增加一个_sidebar.md和打开loadSidebar选项，侧边栏就会自动显示_sidebar.md的内容。

我们只需要在_sidebar.md加上目录信息， 再搭配docsify-sidebar-collapse插件就可以显示以下的效果了：

原理

GitHub Actions 是 GitHub 提供的一种自动化工具，它可以帮助你在 GitHub 仓库中自动执行软件开发的工作流程。你可以使用 GitHub Actions 来构建、测试和部署你的代码。你也可以使用它来自动化其他的任务，例如发送电子邮件通知、创建问题和拉取请求，甚至发布到 GitHub Pages 或其他的云平台。

GitHub Actions 的工作流程是由一系列的任务（称为"actions"）组成的，这些任务可以在同一个虚拟环境中按照你定义的顺序执行。每个任务都可以运行一个命令或者一个脚本，也可以运行一个你从 GitHub Marketplace 或者其他地方获取的预定义的action。

你可以在你的仓库中创建一个 .github/workflows 目录来存放你的工作流程文件。每个工作流程文件都是一个 YAML 文件，它定义了一个或者多个工作流程。当你的仓库中发生一个特定的事件（例如 push、pull request 或者 issue）时，GitHub Actions 就会自动执行相应的工作流程。

如果使用github pages来部署我们的博客，就需要一个github仓库，那这样我们只需要利用github action在代码推送时，都生成一次_sidebar.md，这样就可以保证我们仓库上面的目录一直都是最新的。

_sidebar.md:

- [README.md](./README.md)
- directory1
  - [file1.1.md](./directory1/file1.1.md)
  - [file1.md](./directory1/file1.md)
- directory2
  - [file2.md](./directory2/file2.md)
- directory3
  - [file3.md](./directory3/file3.md)
- [_sidebar.md](./_sidebar.md)

教程

在仓库目录建立一个新文件.github/workflows/main.yml

on: [push] # 在push的时候执行

jobs:
  add_sidebar_job:
    runs-on: ubuntu-latest
    name: job to add _sidebar.md
    steps:
      - uses: actions/checkout@v4                     # 拉取代码
      - uses: if-nil/docsify-file-catalog-action@main # 使用action生成_sidebar.md文件并推送到仓库内
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}   # GITHUB_TOKEN 需要有写权限
          # include: '.*'

docsify-file-catalog-action是一个用来生成_sidebar.md并推送到仓库的action，有两个参数

inputs	描述	必须	默认值
github_token	用来推送_sidebar.md到仓库内，需要写权限	true	null
include	希望显示的文件列表（正则表达式）	false	.*\.md

需要检查一下github_token是否有写权限，位置在仓库的 Setting -> Actions -> General:

然后提交代码即可

git add .github/workflows/main.yml
git commit -m "add workflow"
git push

点击仓库的Action按钮查看执行情况

一切正常的话就可以看到我们的根目录有一个_sidebar.md文件了

参考

• docsify-file-catalog-action
• actions-demo