1+1=10

记记笔记，放松一下...

Hello Pelican Again

Again，为什么说again？？早在2015年接触了到Pelican和GitHub Pages，结果架子搭好了，见：Hello Pelican，但8年间却一直没写东西。希望这次能坚持住。

OK，先升级pelican使得 blog重新工作。

注：只关注在pelican下的markdown的使用。

安装Pelican

好在pelican从python2到python3基本没有变化。

直接安装安装python3，并启用创建虚拟环境

1
python -m venv .venv

激活虚拟环境

1
.venv\Scripts\activate.bat

安装软件包

1
pip install "pelican[markdown]"

安装后记得生成新的 requirements.txt 文件

1
pip freeze > requirements.txt

以便于后期使用(比如GitHub Actions中)

1
pip install -r requirements.txt

Pelican常用命令

直接执行pelican即可让它工作(生成静态页面)

1
pelican

它默认加载当前目录下的 pelicanconf.py文件。如果要使用其他配置文件，可以通过命令行选项 -s指定

1
pelican -s publishconf.py

运行结束后，用浏览器直接打开生成目录(output)下的文件即可看到效果。

也可以启动一个http server：

1
pelican --listen

而后用浏览器访问 http://localhost:8000/

如果从头开始创建一个blog，可以使用quickstart命令

1
pelican-quickstart

它生成的文件中包含makefile（供make使用）和task.py文件（供invoke使用），都可以直接删掉。

Pelican配置

Pelican默认生成2个配置文件pelicanconf.py和publicconf.py。前者默认使用，后者需要通过命令行使用（用于生成发布用的站点）。

  • 详见 https://docs.getpelican.com/en/latest/settings.html

后者一般基于前者进行些改动，比如，它一般都包含：

1
from pelicanconf import *

插件

注意：Pelican 老的插件位于 https://github.com/getpelican/pelican-plugins。如果别的文章，介绍插件时直接指向这个东西，需要注意内容其是否过时。 2023-11-13。

新的插件(位于 https://github.com/pelican-plugins )，可以直接使用 pip 安装，比如

1
pip install pelican-search

安装后，pelican会自动识别它，也无需在pelicanconf.py中配置PLUGINS变量。

注意pelican-search 依赖另外一个名为Stork的东西（Stork作者声明不再更新，但是pelican-search作者认为短期没有替换必要）。

执行如下命令，查看当前安装的插件

1
pelican-plugins

Article与Page

Blog的内容，一般都有时间属性，pelican将其归类于 article；而"关于"，“联系方式” 等页面则不常变化，归于pages。

Pelican Markdown 语法

  • https://docs.getpelican.com/en/stable/content.html

链接格式

主要关注下内部链接的语法，它支持变量。

  • filename

要在一篇博客中引用另外的站内博客，需要使用 filename

1
2
[a link relative to the current file]({filename}category/debao.md)
[a link relative to the content root]({filename}/category/article1.md)
  • static

要在博客中显示静态资源中的图像，需要指定static 。

1
2
![Alt Text]({static}/images/han.jpg)
[Our Menu]({static}/pdfs/menu.pdf)
  • attach
1
2
3
![Icon]({attach}icons/icon.png)
![Photo]({attach}photo.jpg)
[Downloadable File]({attach}/downloads/archive.zip)

注意：pelican的变量格式，和常规的各个markdown编辑器支持的格式不一样。

建议方案：编写 Python Markdown 的 ProProcesser扩展，在内存中自动添加这些变量，以便于让pelican满意。

Meta信息

需要在文件头部添加一些信息，比如：

1
2
3
4
5
title:  Github Actions从0到1笔记（基于Python）
slug: python-examples-with-github-actions
date: 2023-11-12 22:31
category: python
tags: python, github, CI

或者用yaml格式【需要使用相应扩展】

1
2
3
4
5
6
7
---
title:  Github Actions从0到1笔记（基于Python）
slug: python-examples-with-github-actions
date: 2023-11-12 22:31
category: python
tags: [python, github, CI]
---

可用的 MetaData列表：

MetaData 描述
title 标题（Article 或 Page)
date 发布日期， (YYYY-MM-DD HH:SS)
modified 修改日期 (YYYY-MM-DD HH:SS)
tags 逗号分隔
keywords 逗号分隔 (HTML content only)
category 每个article只能指定一个类别)
slug ID，当title有中文时，最好指定它（不然url中会用拼音）。
author 作者
authors 作者们
summary Brief description of content for index pages
lang 语言 (en, fr, etc.)
translation 当前article是否是另一个的翻译 (true or false)
status 状态:draft, hidden, or published
template Name of template to use to generate content (without extension)
save_as Save content to this relative file path
url URL to use for this article/page

注意：title必须出现在第一行，不然会有下面这样的错误：could not find information about 'title'

katex 支持

getpelican使用的python-markdown，理论上用其扩展markdown-katex就行了。

1
pip install markdown_katex

安装后，在getpelican下的启用方式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# pelicanconf.py
MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.codehilite': {'css_class': 'highlight'},
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
        'markdown_katex': {'no_inline_svg': False, 'insert_fonts_css': True}
    },
    'output_format': 'html5',
    }

注意，此处只添加了 markdown_katex，之所以写这么多，是因为其他的是getplican的默认值，不能直接覆盖MARKDOWN变量，不然table、code 都会解析不正常。

20241024更新

当前blog 自己编写Markdown插件，不进行离线转换。速度只需数秒。

配置文件内容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
current_dir = os.path.dirname(os.path.abspath(__file__))
sys.path.insert(0, os.path.join(current_dir, 'plugins', 'debaomdkatex'))
from debaomdkatex import DebaoMdKatexExtension

MARKDOWN = {
    'extensions': [DebaoMdKatexExtension()],
    'extension_configs': {
        'extra': {},
        'codehilite': {'css_class': 'highlight', 'linenums':True},
        'meta': {},
        'toc': {},
        #'markdown_katex': {'no_inline_svg': False, 'insert_fonts_css': True},
        'markdown_mermaidjs': {}
    },
    'output_format': 'html5',
    }

EXTRA_HEADER = """
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" integrity="sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js" integrity="sha384-7zkQWkzuo3B5mTepMUcHkMB5jZaolc2xDwL6VFqjFALcbeS9Ggm/Yr2r3Dy4lfFg" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js" integrity="sha384-43gviWU0YVjaDtb/GhzOouOXtZMP/7XUzwPTstBeZFe/+rCMvRwr4yROQP43s0Xk" crossorigin="anonymous"
    onload="renderMathInElement(document.body);"></script>
"""

mermaid 支持

同katex类似，python中的markdown有对merimad的扩展支持

1
pip install markdown-mermaidjs
  • https://pypi.org/project/markdown-mermaidjs/

getpelican下，配置pelicanconf.py进行启用：

1
2
3
4
5
6
# pelicanconf.py
MARKDOWN = {
    "extension_configs": {
        "markdown_mermaidjs": {},
    },
}

使用GitHub Action发布

目标：自动将生成的静态站点，发布到另外一个仓库中。

GitHub actions的market中有一些其他人些的action，用于发布pelican站点到pages。使用它会大大简化workflow文件，不过这儿用最原始的方式，希望可控性好一些。

在当前仓库中添加一个workflow文件：.github/workflows/pelican.yml

内容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
name: pelican CI for debao blog

on:
  # Trigger the workflow on push on main branch,
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
      with: 
        submodules: 'true'
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.11'
    - name: Install and run pelican
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
        pelican
    - name: depoly to gh pages
      working-directory: ./output
      run: |
        git init
        git remote add blog https://x-access-token:${{secrets.MYBLOG_TOKEN}}@github.com/dbzhang800/myrepoXxxxxxx.git
        git config user.name "Debao Zhang"
        git config user.email "hello@debao.me"
        git add .
        git commit -m "Automated deployment to github pages"
        git push blog HEAD:main --force
        rm -fr .git

为了将代码推送进另一个仓库，创建一个用于目标仓库的Access Token，而后将其作为secrets变量设置到当前仓库中MYBLOG_TOKEN。

Access Token创建方式（点击账户头像）：<Avatar> => Settings => Developer settings => Personal access tokens

参考

  • https://docs.getpelican.com/en/latest/index.html *