使用GitHub作为Markdown图床

Posted 胡争辉

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了使用GitHub作为Markdown图床相关的知识,希望对你有一定的参考价值。

使用GitHub作为Markdown图床

使用GitHub作为Markdown图床

简介

本文讲解如何使用GitHub ActionsMarkdown文件中图片的相对路径转换为绝对路径,
后续将Markdown文件复制到其他位置可以保持图片链接地址,也就是使用GitHub作为Markdown图床。

目前网站已发布在

https://www.xuekaiyuan.com/

已经同步发布在

https://xuekaiyuan.pages.dev/

https://xuekaiyuan.netlify.app/

本文发表在

https://www.xuekaiyuan.com/huzhenghui/pandocomatic/readme.textbundle/

https://xuekaiyuan.pages.dev/huzhenghui/pandocomatic/readme.textbundle/

https://xuekaiyuan.netlify.app/huzhenghui/pandocomatic/readme.textbundle/

https://blog.csdn.net/hu_zhenghui/article/details/128766110

仓库

xuekaiyuan-com/xuekaiyuan-com.github.io仓库

仓库位于https://github.com/xuekaiyuan-com/xuekaiyuan-com.github.io/

相关版本为

v0.3

详见https://www.xuekaiyuan.com/posts/xuekaiyuan/readme/

huzhenghui/posts仓库

仓库位于https://github.com/huzhenghui/posts

本文将使用GitHub ActionsMarkdown文件中图片的相对路径转换为绝对路径,
转换目标为huzhenghui/posts-pandocomatic仓库

相关版本为

https://github.com/huzhenghui/posts/tree/v0.4

huzhenghui/posts-pandocomatic仓库

新建仓库,用于保存生成的文件,位置在

https://github.com/huzhenghui/posts-pandocomatic/

huzhenghui/posts仓库结构

查询命令

find './.github/workflows/pandocomatic.yml'; find './Pandocomatic'; find './dist/Pandocomatic' | as-tree

本文相关文件为

.
├── .github/workflows
│   └── pandocomatic.yml
├── Pandocomatic
│   ├── README.md
│   ├── README.textbundle
│   │   ├── assets
│   │   │   ├── docker.entrypoint.sh.png
│   │   │   ├── image.lua.png
│   │   │   ├── pandocomatic.config.yaml.png
│   │   │   └── workflows.pandocomatic.yml.png
│   │   ├── index.md
│   │   └── text.md
│   ├── assets
│   │   ├── docker.entrypoint.sh.png
│   │   ├── image.lua.png
│   │   ├── pandocomatic.config.yaml.png
│   │   └── workflows.pandocomatic.yml.png
│   ├── docker.entrypoint.sh
│   ├── pandocomatic-data
│   │   └── image.lua
│   └── pandocomatic.yaml
└── dist/Pandocomatic
    └── .gitkeep

创建Personal access tokens

由于需要向仓库提交代码,为避免安全隐患,应当仅能操作huzhenghui/posts-pandocomatic仓库
因此需要使用Github新的Fine-grained personal access
tokens

创建Personal access tokens,设置名称为

API_TOKEN_GITHUB_POSTS_PANDOCOMATIC

仓库访问Repository access选择https://github.com/huzhenghui/posts-pandocomatic/
仓库权限Repository permissions选择

  • Read access to metadata
  • Read and Write access to code

将在设置Repository secrets中使用该值。

设置Repository secrets

访问仓库https://github.com/huzhenghui/posts/Repository secrets设置页面

https://github.com/huzhenghui/posts/settings/secrets/actions

Repository secrets中可以看到已经有三项

  1. TRIGGER_XUEKAIYUAN_COM
  2. TRIGGER_XUEKAIYUAN_PAGES_DEV
  3. TRIGGER_XUEKAIYUAN_NETLIFY_APP

接下来增加一项,名称设置为API_TOKEN_GITHUB_POSTS_PANDOCOMATIC,值设置为前面创建Personal access tokens记录的值。

该设置将在第三步:获取huzhenghui/posts-pandocomatic仓库代码中使用。

.github/workflows/pandocomatic.yml

.github/workflows/pandocomatic.yml程序

手工创建,位置在

https://github.com/huzhenghui/posts/blob/master/.github/workflows/pandocomatic.yml

Since v0.4

https://github.com/huzhenghui/posts/blob/v0.4/.github/workflows/pandocomatic.yml

name: Converted by pandocomatic and publish to https://github.com/huzhenghui/posts-pandocomatic

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["master"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Converted by pandocomatic and publish to https://github.com/huzhenghui/posts-pandocomatic
  pandocomatic:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: rm ./dist/Pandocomatic/.gitkeep
        run: rm ./dist/Pandocomatic/.gitkeep
      - name: clone https://github.com/huzhenghui/posts-pandocomatic
        env:
          API_TOKEN_GITHUB: $ secrets.API_TOKEN_GITHUB_POSTS_PANDOCOMATIC 
        run: git clone --single-branch --depth 1 --branch master https://huzhenghui:$API_TOKEN_GITHUB@github.com/huzhenghui/posts-pandocomatic.git './dist/Pandocomatic/'
      - name: Run Pandocomatic in docker://pandoc/core:2.19-ubuntu
        uses: docker://pandoc/core:2.19-ubuntu
        with:
          entrypoint: "./Pandocomatic/docker.entrypoint.sh"
      - name: user.email
        run: git config --global user.email "hu@daonao.com"
      - name: user.name
        run: git config --global user.name "huzhenghui"
      - name: commit
        run: |
          cd './dist/Pandocomatic/'; \\
          git add --all; \\
          git commit --allow-empty --message='pandoc Trigger'
      - name: push
        run: |
          cd './dist/Pandocomatic/'; \\
          git push origin

.github/workflows/pandocomatic.yml触发工作流的事件

其中onGitHub Action触发工作流的事件。

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["master"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

.github/workflows/pandocomatic.yml工作流中所有作业的默认设置

其中defaults设置了工作流中所有作业的默认设置,这里默认使用bash运行。

# Default to bash
defaults:
  run:
    shell: bash

.github/workflows/pandocomatic.yml工作流作业

jobs中为工作流中运行的作业,其中只有一个作业pandocomatic

jobs:
  # Converted by pandocomatic and publish to https://github.com/huzhenghui/posts-pandocomatic
  pandocomatic:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: rm ./dist/Pandocomatic/.gitkeep
        run: rm ./dist/Pandocomatic/.gitkeep
      - name: clone https://github.com/huzhenghui/posts-pandocomatic
        env:
          API_TOKEN_GITHUB: $ secrets.API_TOKEN_GITHUB_POSTS_PANDOCOMATIC 
        run: git clone --single-branch --depth 1 --branch master https://huzhenghui:$API_TOKEN_GITHUB@github.com/huzhenghui/posts-pandocomatic.git './dist/Pandocomatic/'
      - name: Run Pandocomatic in docker://pandoc/core:2.19-ubuntu
        uses: docker://pandoc/core:2.19-ubuntu
        with:
          entrypoint: "./Pandocomatic/docker.entrypoint.sh"
      - name: user.email
        run: git config --global user.email "hu@daonao.com"
      - name: user.name
        run: git config --global user.name "huzhenghui"
      - name: commit
        run: |
          cd './dist/Pandocomatic/'; \\
          git add --all; \\
          git commit --allow-empty --message='pandoc Trigger'
      - name: push
        run: |
          cd './dist/Pandocomatic/'; \\
          git push origin

运行pandocomatic作业的计算机类型

运行环境为最新版的Ubuntu

    runs-on: ubuntu-latest

可用运行环境在https://github.com/actions/runner-images,目前(2023年1月26日)可用运行环境如下

镜像YAML 标签包含软件最新镜像进度
Ubuntu 22.04ubuntu-latest or ubuntu-22.04[ubuntu-22.04][外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-PRqsf7yr-1674721570692)(null)]
Ubuntu 20.04ubuntu-20.04[ubuntu-20.04][外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-eCCG68lt-1674721571082)(null)]
Ubuntu 18.04 deprecatedubuntu-18.04[ubuntu-18.04][外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-HmGEI6u0-1674721570974)(null)]
macOS 12macos-latest or macos-12[macOS-12][外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-uFQ65faP-1674721571216)(null)]
macOS 11macos-11[macOS-11][外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-n0mFsevP-1674721571150)(null)]
macOS 10.15 deprecatedmacos-10.15[macOS-10.15][外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-YC62C3i5-1674721570766)(null)]
Windows Server 2022windows-latest or windows-2022[windows-2022][外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-qPTMTw7T-1674721570838)(null)]
Windows Server 2019windows-2019[windows-2019][外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-V8Vm428t-1674721570905)(null)]

第一步:获取huzhenghui/posts仓库代码

      - name: Checkout
        uses: actions/checkout@v3

第二步:删除文件夹./dist/Pandocomatic/的占位文件

      - name: rm ./dist/Pandocomatic/.gitkeep
        run: rm ./dist/Pandocomatic/.gitkeep

删除后,文件夹./dist/Pandocomatic/将是空文件夹,以便于第三步:获取huzhenghui/posts-pandocomatic仓库代码

第三步:获取huzhenghui/posts-pandocomatic仓库代码

此时./dist/Pandocomatic/已是空文件夹,
接下来获取huzhenghui/posts仓库代码到./dist/Pandocomatic/文件夹。

      - name: clone https://github.com/huzhenghui/posts-pandocomatic
        env:
          API_TOKEN_GITHUB: $ secrets.API_TOKEN_GITHUB_POSTS_PANDOCOMATIC 
        run: git clone --single-branch --depth 1 --branch master https://huzhenghui:$API_TOKEN_GITHUB@github.com/huzhenghui/posts-pandocomatic.git './dist/Pandocomatic/'

其中API_TOKEN_GITHUB设置Repository secrets中设置的值。

        env:
          API_TOKEN_GITHUB: $ secrets.API_TOKEN_GITHUB_POSTS_PANDOCOMATIC 

获取代码的命令为

git clone --single-branch --depth 1 --branch master https://huzhenghui:$API_TOKEN_GITHUB@github.com/huzhenghui/posts-pandocomatic.git './dist/Pandocomatic/'

为提升自动化更新代码的速度,所以使用--single-branch仅获取一个分支,使用--depth 1仅获取最后的状态,并指定分支名称--branch master

第四步:在PandocDocker镜像中安装并运行Pandocomatic

      - name: Run Pandocomatic in docker://pandoc/core:2.19-ubuntu
        uses: docker://pandoc/core:2.19-ubuntu
        with:
          entrypoint: "./Pandocomatic/docker.entrypoint.sh"

运行pandocomatic作业的计算机类型可知,
GitHub Action可以选择的最新版本的Ubuntu的版本是ubuntu-22.04

搜索Ubuntu的预编译包https://packages.ubuntu.com/search?keywords=pandoc可以看到,
ubuntu-22.04中的pandoc的版本是2.9.2.1-3ubuntu2,查询pandoc网站可知,
2.9.2.1版本在2020年03月23日发布,
为使用和开发环境一直的较新版pandoc,这一步使用PandocDocker镜像。

        uses: docker://pandoc/core:2.19-ubuntu

PandocDocker镜像在https://hub.docker.com/r/pandoc/core
查询可用版本https://hub.docker.com/r/pandoc/core/tags
选择和开发环境最接近的https://hub.docker.com/r/pandoc/core/tags?name=2.19-ubuntu
因为镜像中没有pandocomatic,所以需要安装并运行pandocomatic
因此编写脚本./Pandocomatic/docker.entrypoint.sh
使用参数entrypoint指定镜像中运行脚本的路径。

        with:
          entrypoint: "./Pandocomatic/docker.entrypoint.sh"

第五步:设置Git用户邮箱

第七步:提交代码中需要设置user.email参数。

      - name: user.email
        run: git config --global user.email "hu@daonao.com"

第六步:设置Git用户名

第七步:提交代码中需要设置user.name参数。

      - name: user.name
        run: git config --global user.name "huzhenghui"

第七步:提交代码

      - name: commit
        run: |
          cd './dist/Pandocomatic/'; \\
          git add --all; \\
          git commit --allow-empty --message='pandoc Trigger'

先进入第三步:获取huzhenghui/posts-pandocomatic仓库代码中获取代码的路径,
此时代码已经在第四步:在PandocDocker镜像中安装并运行Pandocomatic中被脚本./Pandocomatic/docker.entrypoint.sh更新。

cd './dist/Pandocomatic/';

添加全部文件

git add --all

提交文件

git commit --allow-empty --message='pandoc Trigger'

因为是自动运行,因此在第四步:在PandocDocker镜像中安装并运行Pandocomatic中生成的文件可能和已有文件完全相同,也就是没有文件被更新,因此提交时使用允许无文件的参数--allow-empty

第八步:推送

      - name: push
        run: |
          cd './dist/Pandocomatic/'; \\
          git push origin

Github Action中每一步的运行环境相同,因此也需要先进入第三步:获取huzhenghui/posts-pandocomatic仓库代码中获取代码的路径。

cd './dist/Pandocomatic/';

再推送

git push origin

./Pandocomatic/docker.entrypoint.sh

第四步:在PandocDocker镜像中安装并运行Pandocomatic中讲到在镜像中需要通过脚本运行Pandocomatic

脚本位置在

https://github.com/huzhenghui/posts/blob/master/Pandocomatic/docker.entrypoint.sh

Since v0.4

https://github.com/huzhenghui/posts/blob/v0.4/Pandocomatic/docker.entrypoint.sh

#!/bin/sh
echo 打印系统上安装的 pandoc 版本。
pandoc --version
echo 列出目录 ./dist/Pandocomatic/ 中的文件
ls -al ./dist/Pandocomatic/
echo 使用 apt-get update 更新包索引
apt-get update
echo 使用 apt-get 安装 Ruby
apt-get install --assume-yes --no-install-recommends ruby
echo 使用 gem 安装 pandocomatic
gem install pandocomatic
echo 使用配置文件 ./Pandocomatic/pandocomatic.yaml 运行 pandocomatic
pandocomatic --debug --input . --output ./dist/Pandocomatic/ --config ./Pandocomatic/pandocomatic.yaml

打印系统上安装的pandoc版本。

pandoc --version

运行输出为

pandoc 2.19.2
Compiled with pandoc-types 1.22.2.1, texmath 0.12.5.2, skylighting 0.13,
citeproc 0.8.0.1, ipynb 0.2, hslua 2.1.0
Scripting engine: Lua 5.3
User data directory: /github/home/.local/share/pandoc
Copyright (C) 2006-2022 John MacFarlane. Web:  https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

用于核对运行版本。

列出目录./dist/Pandocomatic/中的文件

ls -al ./dist/Pandocomatic/

运行输出为

drwxr-xr-x 7 1001 123 4096 Jan 26 04:02 .
drwxr-xr-x 3 1001 123 4096 Jan 26 04:02 ..
drwxr-xr-x 8 1001 123 4096 Jan 26 04:02 .git
drwxr-xr-x 2 1001 123 4096 Jan 26 04:02 Cloudflare
drwxr-xr-x 2 1001 123 4096 Jan 26 04:02 GitHub
drwxr-xr-x 2 1001 123 4096 Jan 26 04:02 Netlify
drwxr-xr-x 4 1001 123 4096 Jan 26 04:02 Pandocomatic
-rw-r--r-- 1 1001 123   99 Jan 26 04:02 _index.md

用于检查第三步:获取huzhenghui/posts-pandocomatic仓库代码的运行情况。

使用apt-get update更新包索引。

apt-get update

使用apt-get安装Ruby

apt-get install --assume-yes --no-install-recommends ruby

使用gem安装pandocomatic

gem install pandocomatic

使用配置文件./Pandocomatic/pandocomatic.yaml运行pandocomatic

pandocomatic --debug --input . --output ./dist/Pandocomatic/ --config ./Pandocomatic/pandocomatic.yaml

输入文件夹为当前目录.,也就项目根目录,输出目录为第三步:获取huzhenghui/posts-pandocomatic仓库代码的位置,也就是覆盖huzhenghui/posts-pandocomatic仓库的文件。

./Pandocomatic/pandocomatic.yaml

由于参数较多,在./Pandocomatic/docker.entrypoint.sh中运行pandocomatic时使用配置文件。

配置文件位置在

https://github.com/huzhenghui/posts/blob/master/Pandocomatic/pandocomatic.yaml

Since v0.4

https://github.com/huzhenghui/posts/blob/v0.4/Pandocomatic/pandocomatic.yaml

settings:
  data-dir: ./pandocomatic-data/
  recursive: true
  skip:
    - dist
templates:
  md:
    glob: ["*.md"]
    metadata:
      IMAGE_PREFIX: https://raw.githubusercontent.com/huzhenghui/posts/master/
    pandoc:
      from: markdown
      to: gfm
      lua-filter: image.lua

其中settingsPandocomatic设置。

settings:
  data-dir: ./pandocomatic-data/
  recursive: true
  skip:
    - dist

data-dir指定Pandocomatic的数据文件夹为./pandocomatic-data/目录,
也就是Pandocomatic/pandocomatic-data/image.lua的路径。

recursive设置为true,表示递归转换子文件夹。

skip指定跳过的文件夹,由于dist文件夹用于保存第三步:获取huzhenghui/posts-pandocomatic仓库代码,因此需要设置为跳过dist文件夹。

templates定义Pandocomatic的模板,配置中只有一个模板md

templates:
  md:
    glob: ["*.md"]
    metadata:
      IMAGE_PREFIX: https://raw.githubusercontent.com/huzhenghui/posts/master/
    pandoc:
      from: markdown
      to: gfm
      lua-filter: image.lua

glob参数用于匹配转换的文件名,*.md表示匹配扩展名为.md的文件。

metadata用于设置pandoc所使用的元数据,
此处为元数据项IMAGE_PREFIX的值为https://raw.githubusercontent.com/huzhenghui/posts/master/
用于在Pandocomatic/pandocomatic-data/image.lua添加为图片的前缀路径。

pandoc为调用pandoc的参数,frompandoc--from参数,markdown表示输入格式为markdown
topandoc--to参数,gfm表示输出格式为Github-Flavored Markdown,也就是Github风格的markdown
lua-filterpandoc--lua-filter参数,指定Lua脚本的路径,也就是Pandocomatic/pandocomatic-data/image.lua的路径,由于data-dir指定Pandocomatic的数据文件夹为./pandocomatic-data/目录,因此值为相对路径image.lua

Pandocomatic/pandocomatic-data/image.lua

在配置文件./Pandocomatic/pandocomatic.yaml设置pandoc运行时的lua脚本。

lua脚本文件位置在

https://github.com/huzhenghui/posts/blob/master/Pandocomatic/pandocomatic-data/image.lua

Since v0.4

https://github.com/huzhenghui/posts/blob/v0.4/Pandocomatic/pandocomatic-data/image.lua

-- 图片地址前缀
local image_prefix
-- markdown 文件夹的根目录
local root
-- markdown_path 是正在转换的 markdown 文件的路径
local markdown_path
-- 从元数据中提取元数据变量
function extract_metadata_vars (meta)
    -- 枚举元数据中的变量
    for k, v in pairs(meta) do
        -- 从元数据中提取 IMAGE_PREFIX 变量
        if k == 'IMAGE_PREFIX' then
            -- pandoc.utils.stringify(v) 是一个将变量转换为字符串的函数
            image_prefix = pandoc.utils.stringify(v)
        end
        -- 获取 pandocomatic 设置的文件的信息
        if k == 'pandocomatic-fileinfo' then
            -- 获取 markdown 文件的路径和 markdown 文件的根目录。
            for k1,v1 in pairs(v) do
                -- src_path 是 markdown 文件的文件夹的根目录
                if k1 == 'src_path' then
                    -- root 是 markdown 文件的根目录
                    root = pandoc.utils.stringify(v1)
                end
                -- 获取 markdown 文件的路径
                if k1 == 'path' then
                    -- markdown_path 是 markdown 文件的路径
                    markdown_path = pandoc.utils.stringify(v1)
                end
            end
        end
    end
end
-- 将图像路径转换为 URL 的函数
function image_converter(elem)
    -- 检查图像是否已经是 URL。如果是,它什么也不做。如果不是,它将图像路径转换为 URL。
    if elem.src:find('https://', 1, true) ~= 1 then
        -- directory 是 markdown 文件的目录
        directory = pandoc.path.directory(markdown_path)
        -- pandoc.path.join 是连接两条路径的函数,结果为图像的绝对路径。
        image_absolute_path = pandoc.path.join(directory, elem.src)
        -- image_relative_root_path 是图片相对于 markdown 文件根目录的路径。
        image_relative_root_path = pandoc.path.make_relative(image_absolute_path, root)
        -- image_prefix 是 URL 的前缀,拼接图片相对路径得到image_url 是图片的 URL。
        image_url = image_prefix .. image_relative_root_path
        -- 更改 Image 元素的 src 属性的值为图片的 URL。
        elem.src = image_url
    end
    -- 返回修改后的元素。
    return elem
end
-- 返回函数钩子
return 
    -- Meta = extract_metadata_vars 是将应用于元数据的过滤器。
    Meta = extract_metadata_vars,
    -- 将 image_converter 函数应用于所有 Image 元素。
    Image = image_converter

Pandocomatic/pandocomatic-data/image.lua本地变量

脚本中包含三个本地变量

extract_metadata_vars函数

-- 从元数据中提取元数据变量
function extract_metadata_vars (meta)
    -- 枚举元数据中的变量
    for k, v in pairs(meta) do
        -- 从元数据中提取 IMAGE_PREFIX 变量
        if k == 'IMAGE_

以上是关于使用GitHub作为Markdown图床的主要内容,如果未能解决你的问题,请参考以下文章

Windows环境下Typora+PicGo+Github图床让Markdown编辑起飞

Windows环境下Typora+PicGo+Github图床让Markdown编辑起飞

Markdown 新解决方案:Typora+本地备份+GitHub 图床

基于MarkDown和Github图床以及SourceTree的一站式文章编辑和发布

笔记神器Markdown之完美实现图床(Typora+PicGo+Github)

自制永久免费的私有图床,替代iPic,你值得拥有