Again,为什么说again??早在2015年接触了到Pelican和GitHub Pages,结果架子搭好了,8年间却一直没写东西。希望这次能坚持住:Hello Pelican。
OK,先升级pelican使得 blog重新工作。
安装Pelican
好在pelican从python2到python3基本没有变化。
直接安装安装python3,并启用创建虚拟环境
python -m venv .venv
激活虚拟环境
.venv\Scripts\activate.bat
安装软件包
pip install "pelican[markdown]"
安装后记得生成新的 requirements.txt 文件
pip freeze > requirements.txt
以便于后期使用(比如GitHub Actions中)
pip install -r requirements.txt
Pelican常用命令
直接执行pelican即可让它工作
pelican
它默认加载当前目录下的pelicanconf.py
文件。如果要使用其他配置文件,可以通过命令行指定
pelican -s publishconf.py
运行结束后,用浏览器直接打开生成目录(output)下的文件即可看到效果。
也可以启动一个http server:
pelican --listen
而后用浏览器访问 http://localhost:8000/
如果从头开始创建一个blog,可以使用quickstart命令
pelican-quickstart
它生成的文件中包含makefile(供make使用)和task.py文件(供invoke使用),都可以直接删掉。
Pelican配置
Pelican默认生成2个配置文件pelicanconf.py和publicconf.py。前者默认使用,后者需要通过命令行使用(用于生成发布用的站点)。
- 详见 https://docs.getpelican.com/en/latest/settings.html
后者一般基于前者进行些改动,比如,它一般都包含:
from pelicanconf import *
插件
注意:Pelican 老的插件位于 https://github.com/getpelican/pelican-plugins。如果别的文章,介绍插件时直接指向这个东西,需要注意内容其是否过时。 2023-11-13。
新的插件(位于 https://github.com/pelican-plugins ),可以直接使用 pip 安装,比如
pip install pelican-search
安装后,pelican会自动识别它,也无需在pelicanconf.py中配置PLUGINS变量。
注意pelican-search 依赖另外一个名为Stork的东西(Stork作者声明不再更新,但是pelican-search作者认为短期没有替换必要)。
执行如下命令,查看当前安装的插件
pelican-plugins
Article与Page
Blog的内容,一般都有时间属性,pelican将其归类于 article;而"关于",“联系方式” 等页面则不常变化,归于pages。
Pelican Markdown 语法
- https://docs.getpelican.com/en/stable/content.html
链接格式
主要关注下内部链接的语法
- filename
要在一篇博客中引用另外的站内博客,需要使用 filename
[a link relative to the current file]({filename}category/debao.md)
[a link relative to the content root]({filename}/category/article1.md)
- static
要在博客中显示静态资源中的图像,需要指定static 。

[Our Menu]({static}/pdfs/menu.pdf)
- attach


[Downloadable File]({attach}/downloads/archive.zip)
Meta信息
需要在文件头部添加一些信息,比如:
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'
使用GitHub Action发布
目标:自动将生成的静态站点,发布到另外一个仓库中。
GitHub actions的market中有一些其他人些的action,用于发布pelican站点到pages。使用它会大大简化workflow文件,不过这儿用最原始的方式,希望可控性好一些。
在当前仓库中添加一个workflow文件:.github/workflows/pelican.yml
内容如下:
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@v3
with:
submodules: 'true'
- name: Set up Python
uses: actions/setup-python@v3
- 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