小技巧¶

以下是一些实用的小技巧。

自定义404页面¶

当浏览器请求的资源无法在服务器中找到时，web服务器常常会显示一个通用的“File not found 404”的错误页面，这可能会不太美观。为了能使用一个与站点主题相匹配的404页面（注意是页面而不是文章），例如下面这个Markdown格式的例子，将此文件存为了 content/pages/404.md ：

Title: Not Found
Status: hidden
Save_as: 404.html

The requested item could not be located. Perhaps you might want to check
the [Archives](/archives.html)?

接下来就是要配置web服务器，使其显示此自定义页面而不是默认的404页面。例如对于Nginx，在配置文件的 location 块中添加下面的命令：

error_page 404 /404.html;

对于Apache：

ErrorDocument 404 /404.html

对于Amazon S3实例，先在控制台的设置中找到 Static Site Hosting ，并添加：

Error Document: 404.html

发布到GitHub Pages¶

如果将Pelican站点放在了 GitHub 上，那么你就可以将站点免费发布在 GitHub Pages 上。如果是用户或组织的站点，发布的地址为 https://<username>.github.io ；如果是某个项目的站点，发布的地址则为 https://<username>.github.io/<repository> 。当然也可以在GitHub Pages上使用自定义域名。

总的来说，有两种将站点发布到GitHub Pages的方法：

从某一分支发布： 在本地运行 pelican 后将输出文件夹push到GitHub仓库的某一分支。GitHub就会将该分支的内容发布到GitHub Pages上。
从自定义GitHub Actions工作流发布： 将内容源文件推送到GitHub仓库的默认分支，然后在GitHub Actions工作流中执行 pelican 以生成输出文件夹，最后将其发布到你的GitHub Pages站点。此种方法下就无需在本地执行 pelican 命令了。甚至可以直接在GitHub的网页中在线修改站点内容源文件。

从某一分支发布项目站点到GitHub Pages¶

要将Pelican站点发布为项目页面，你需要将Pelican生成的 output 目录 push 到GitHub仓库的 gh-pages 分支。

可通过 pip 安装的 ghp-import 使这一步变得非常简单。

例如，当Pelican站点的源文件已经包含在GitHub仓库中时，可以将其作为此仓库的项目页面：

$ pelican content -o output -s pelicanconf.py
$ ghp-import output -b gh-pages
$ git push origin gh-pages

ghp-import output 命令会用 output 目录下的内容更新本地的 gh-pages 分支（如果此分支不存在则会先创建）。接着再用 git push origin gh-pages 命令更新远程分支 gh-pages ，如此就能够发布Pelican站点了。

备注

pelican-quickstart 在Makefile文件中所生成的 github 目标（以及为 gh_pages 任务生成的 tasks.py ）使得Pelican站点能像上面描述的那样被发布为项目页面。

从某一分支发布用户站点到GitHub Pages¶

要以用户页面形式发布Pelican站点，你需要将Pelican生成的 output 目录内容 push 到 <username>.github.io 仓库的 master 分支上。

同样的，此处也可以使用 ghp-import ：

$ pelican content -o output -s pelicanconf.py
$ ghp-import output -b gh-pages
$ git push git@github.com:elemoine/elemoine.github.io.git gh-pages:main

git push 命令将本地的 gh-pages 分支（此分支在刚刚通过 ghp-import 命令进行了更新）push到了GitHub仓库 elemoine.github.io 的 master 分支。

备注

要将Pelican站点发布为用户页面，可以根据需要修改Makefile中的 github 目标。

发布用户页面的另一种方法就是将输出文件生成在项目的根目录下。

例如，项目的主文件夹是 <username>.github.io ，你可以在子目录 Pelican 中创建一个Pelican项目。然后你可以在这个 Pelican 文件夹中执行下面的命令：

$ pelican content -o .. -s pelicanconf.py

接着可以将整个项目 <username>.github.io push到GitHub仓库的master分支中：

$ git push origin main

（此处假设远程仓库命名为origin）。

使用自定义GitHub Actions工作流将站点发布GitHub Pages中¶

Pelican已经给你准备了一份自定义工作流，你可以直接使用此工作流发布站点：

首先为仓库开启GitHub Pages： Settings → Pages 中有个 Source 设置项，将其选择为 GitHub Actions 。
往你的仓库中commit一个 .github/workflows/pelican.yml 文件，文件内容如下：
```
name: Deploy to GitHub Pages
on:
  push:
    branches: ["main"]
  workflow_dispatch:
jobs:
  deploy:
    uses: "getpelican/pelican/.github/workflows/github_pages.yml@main"
    permissions:
      contents: "read"
      pages: "write"
      id-token: "write"
    with:
      settings: "publishconf.py"
```
你可能想要将 @main 替换为这个仓库中某个特定commit的ID，以便将你使用的可重用工作流的版本固定下来，此时，可以使用 uses: getpelican/pelican/.github/workflows/github_pages.yml@<COMMIT_ID> 。在这种情况下，你可能想让Dependabot自动向你发送PR，以便在发布新版本的工作流时更新commit ID，如下所示:
```
# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "monthly"
```
请参阅 GitHub文档，了解如何使用Dependabot使您的action保持最新。
选中仓库的 Actions 标签栏（ https://github.com/<username>/<repository>/actions ），此时你应该会看到已经有一个名为 Deploy to GitHub Pages 的action正在运行。
当此action执行完成，就能够通过仓库的GitHub Pages地址 https://<username>.github.io 看到部署好了的用户或组织站点了，对于项目站点，可通过 https://<username>.github.io/<repository> 访问。

注意事项：

无需在Pelican配置文件中设置 SITEURL ，工作流会帮你进行设置。
无需commit --output 或 OUTPUT_PATH 所指定的目录（ output/ ）：工作流会自己执行 pelican 命令来构建输出目录。

更多信息请参阅 GitHub可重用工作流文档。

有一些可选输入可以添加到工作流的 with: 块中：

with:
  settings: "publishconf.py"
  requirements: "pelican[markdown] typogrify"
  theme: "https://github.com/seanh/sidecar.git"
  python: "3.12"

下面是工作流可用输入参数的完整列表：

名称	是否必需	描述	值的类型	默认值
`settings`	是	Pelican配置文件的路径（会被用于 `pelican` 命令的 `--settings` 选项），例如 `"publishconf.py"` 。	string
`requirements`	否	需要安装的Python模块，例如要开启markdown和typogrify，可指定 `"pelican[markdown] typogrify"` ，或者可以指定一个requirements文件： `"-r requirements.txt"`	string	`"pelican"`
`output-path`	否	生成文件的输出位置（会被用于 `pelican` 命令的 `--output` 选项）	string	`"output/"`
`theme`	否	要使用的自定义主题的GitHub仓库URL，例如： `"https://github.com/seanh/sidecar.git"`	string	`""`
`theme-checkout`	否	主题仓库要checkout的Git引用 (branch, tag 或 commit)。这可以用于固定主题的版本。若未指定，使用仓库的默认branch。	string	`""`
`python`	否	构建站点时使用的Python版本，例如： `"3.12"` 或 `"3.12.1"`	string	`"3.12"`
`siteurl`	否	站点的基URL，会用于配置项 `SITEURL` 。若未指定，默认值为GitHub Pages站点的URL，这适用于大部分情况。	string	GitHub Pages站点的URL
`feed_domain`	否	订阅源URL前要附加的域名，会用于配置项 `FEED_DOMAIN` 。若未指定，默认值为GitHub Pages站点的URL，这适用于大部分情况。	string	GitHub Pages站点的URL
`deploy`	否	此项配置用于表示是否要将站点部署至GitHub Pages。当对站点做了更改，并且在正式部署前进行测试，就可以用到此项。	bool	`true`
`stork`	否	此配置项用于指定是否要在runner中安装Stork搜索。	bool	`false`

在Github拉取请求时进行测试¶

如果想在正式部署到 GitHub 前在PR中进行测试，下面是一个可用的 workflow 示例

name: Build and Deploy Site
on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
  workflow_dispatch:
    inputs:
      deploy:
        required: false
        default: true
        description: "Whether to deploy the site. If checked, then build the site and deploy it. If not checked, then just test that the site builds successfully but don't deploy anything."
        type: boolean
jobs:
  deploy:
    uses: "getpelican/pelican/.github/workflows/github_pages.yml@main"
    permissions:
      id-token: write
      contents: read
      pages: write
    with:
      settings: "publishconf.py"
      requirements: "-r requirements.txt"
      deploy: ${{ (github.event_name == 'workflow_dispatch' && inputs.deploy == true) || (github.event_name == 'push' && github.ref_type == 'branch' && github.ref_name == github.event.repository.default_branch) }}

工作流的 on 部分定义了工作流的触发器。在此示例中，工作流将在main分支收到push、有PR提起到主分支以及手动运行工作流时执行。

workflow_dispatch 将 deploy 的默认值设为 true。也就是说当手动运行工作流时，更改的内容就会正式部署。

job中的 deploy 使用了一些 GitHub workflow 变量来计算 deploy 值为 true 还是 false（您可以根据需要自定义）。

在此示例中，如果触发事件是推送到主分支（或从 PR 合并到主分支）或手动运行工作流，则 deploy 将为 true；如果触发事件只是Pull Request，则 deploy 将为 false，并且此时只会为站点构建一个artifact。

浏览器报“不安全的内容（Insecure content）”警告¶

当站点使用 https:// 时，可能会损坏，无法正常显示，这是由于浏览器阻拦了一些对“不安全内容”的网络请求。可能的原因之一是GitHub Pages给你的站点生成了 http:// URL。

要想解决这一问题，需要为站点所在仓库开启 强制使用HTTPS ：点击 Settings → Pages 并在其中勾选 Enforce HTTPS ，接着再重新执行工作流以重新部署站点。也可以尝试通过配置 siteurl 与 feed_domain 解决问题。

自定义404页面¶

如果按前述进行配置，GitHub Pages是能够正确显示自定义的404页面的，相关内容在 GitHub的文档中也有提到。

在每次commit后都更新站点¶

要想在每次commit后自动更新Pelican站点，你可以创建一个post-commit钩子。例如，可以将下面的内容保存为 .git/hooks/post-commit ：

pelican content -o output -s pelicanconf.py && ghp-import output && git push origin gh-pages

将静态文件拷贝到站点根目录¶

要将自定义域名与GitHub Pages一起使用，需要将站点的域名（例如 blog.example.com ）添加到站点根目录的 CNAME 文件中。为此，请创建 content/extra/ 目录，并在里面添加一个 CNAME 文件。然后使用Pelican的 STATIC_PATHS 来告诉Pelican将此文件复制到输出目录：

STATIC_PATHS = ['images', 'extra/CNAME']
EXTRA_PATH_METADATA = {'extra/CNAME': {'path': 'CNAME'},}

请注意：务必使用正斜杠 / ，在Windows上也是。

利用 EXTRA_PATH_METADATA 机制，你可以将 favicon.ico 或 robots.txt 也拷贝到站点的根目录下。

如何添加YouTube或Vimeo视频¶

最简单的方法是将这些网站的视频嵌入代码直接粘贴到您的源内容文件中。

或者，您还可以使用例如 liquid_tags 、pelican_youtube 或 pelican_vimeo 等Pelican插件将视频嵌入。

此外，像reST和 Markdown这样的标记语言都有对应插件可以让你在其中嵌入视频。可以使用 reST的视频指令或者 Markdown的mdx_video插件。

在本地使用SSL进行开发¶

以下描述了如何在本地Pelican服务器上配置SSL。

首先，通过 openssl 创建自签名的证书和密钥，这会生成 cert.pem 和 key.pem 文件：

$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

接着使用下面的命令来开启服务器（此服务器会在 output 目录下开启）：

python -m pelican.server 8443 --key=../key.pem --cert=../cert.pem

如果你使用的是 develop-server.sh 脚本，在脚本的开头添加：

CERT="$BASEDIR/cert.pem"
KEY="$BASEDIR/key.pem"

然后修改按照下述修改 pelican.server 一行：

$PY -m pelican.server $port --ssl --cert="$CERT" --key="$KEY" &