章峰的网站 - 网站

pelican 创建静态网站

2026-07-01T15:48:00+08:00

介绍¶

之前用过hexo和hugo搭建静态网站，确实可以快速生一个网页，详细信息见免费创建个人静态网站最佳实践：hugo+github+netlify。但是由于不懂JavaScript和GO语言，没有办法对网页样式进行细致地调整。此外，由于它们所使用主题的不断更新，可很难与自己的网站合并，导致网站出问题。实践中发现，主题什么的简单一点好，更主要是把精力放到内容创作上，因此我对网站生成器的要求变为：

主要使用python语法
配置要简单，不用花精力在配置上。
没事不要去折腾主题

Perlican是用Python实现的一个静态网站生成器，支持reStructuredText或Markdown。它支持以下功能：

博客文章和静态网页
支持评论。评论是通过第三方服务Disqus支持的。即评论数据保存在第三方服务器上
主题支持
把博客文章生成PDF格式文档
多语言博客支持，如可以用英文和中文写同一篇博客。不同语言访问者访问相应语言的博文
支持Atom/RSS订阅
博文中代码高亮支持
博客搬家支持(WordPress, Dotclear, 或RSS feeds)
支持插件，如Twiter, Google Analytics等

快速开始¶

# 1 安装
conda create -n pelican python=3.11
conda activate pelican
pip install "pelican[markdown]" # 安装pelican
pip install pelican-i18n-subsites # 双语翻译，不需要不用安装
pip install beautifulsoup4 # 安装toc插件依赖
pip install pymdown-extensions # latex 渲染

# 2 创建目录
mkdir -p ~/projects/myblog
cd ~/projects/myblog

# 3 初始设置
pelican-quickstart

# 4. 输出静态网页
pelican content

# 5 本地展示
pelican --listen
# 或者在开发过程中，希望内容有变化本地网页同时变化，而不需要重新运行 --listen
pelican -r -l # 

# 6 发布到github page展示
pelican content -s publishconf.py
cd output
git init
git remote add origin XX # 如git@github.com:Feng-Zhang/blog-content.git
git push
# https://Feng-Zhang.github.io/blog-content/ 可以在网站上看到内容

这些代码可以快速生成一个网站，但是想让网站变成你心目中的样子还需要进行更多地配置。下面进行详细解释。

内容¶

最简单的方法是使用markdown进行编写。和一般的markdown有点区别的是，需要在开头写明metadata信息，方便网站进行引用。常用的metadata有以下几种：

Title: 标题
Date: 创建时间
Modified: 修改时间
Category: 分类，一般只有一个
Tags: 标签，可以有多个
Slug: 文章的URL别名，只有一个
Authors: Feng Zhang
Lang: zh

发布¶

写的网站如何进行发布呢？一般得买域名并进行渲染，这个有点麻烦。有个最简单的方法是使用Github Pages，即把生成好的静态文件（HTML/CSS/JS）上传到 GitHub 仓库的指定仓库，然后 GitHub 自动帮你部署成网站。访问网址为https://username.github.io/仓库名，比如我把静态文件上传blog-content仓库，访问网站即为 https://feng-zhang.github.io/blog-content/。

把output下文件push到github后，打开网站后是404，原因是github page没有配置。 GitHub Pages 不会自动帮你把仓库“变成网站”，需要进行配置： 1.去 GitHub 仓库：Settings → Pages 2.然后设置：

Source: Deploy from a branch
Branch: master
Folder: / (root)

设置¶

详细配置示例可以到https://github.com/Feng-Zhang/blog-pelican/blob/master/pelicanconf.py 查看，把个性化的东西进行更改就行。

时间和日期¶

LOCALE：控制博客“时间/日期/语言显示风格”，让文章看起来符合中文或英文习惯。

插件¶

pelican从3.0版本开始支持插件。通过插件，不必直接修改Pelican的核心代码就可以给Pelican添加新功能。

1 如何使用插件¶

Pelican从4.5版本开始使用了一种全新的插件结构，利用了命名空间包，并且可以轻松地通过 Pip 进行安装。支持此结构地插件都会被安装在命名空间包 pelican.plugins 下，因此Pelican可以自动发现他们。下面的命令可以用于查看环境中用Pip安装的所有插件：pelican-plugins

若将 PLUGINS 配置项设为默认的 None ，Pelican会自动发现命名空间中的插件并且将他们全部加载；若你在 PLUGINS 设置项中指定了一系列的插件，Pelican就不会去自动发现插件，也就是说，你需要显式地指定所有要使用的插件。在配置 PLUGINS 时，有两种方式。一是用字符串列表指定插件的名称，可以是包含命名空间的完整名称（例如 pelican.plugins.myplugin ），也可以是简短名称（ myplugin）：

PLUGINS = ['package.myplugin',
           'namespace_plugin1',
           'pelican.plugins.namespace_plugin2']

二是在设置文件中先import进来，再将import进的模块放在 PLUGINS 设置项中：

from package import myplugin
from pelican.plugins import namespace_plugin1, namespace_plugin2
PLUGINS = [myplugin, namespace_plugin1, namespace_plugin2]

在尝试不同的插件时（尤其是那些处理元数据和内容的插件），缓存可能会相互干扰，一些更改不会生效。发生这种情况时，就需要通过设置 LOAD_CONTENT_CACHE = False 或使用 --ignore-cache 命令行选项禁用缓存。如果插件处于无法直接进行import的路径，可以在 PLUGIN_PATHS 配置项中指定这些路径。如下例所示， PLUGIN_PATHS 中的路径可以是绝对的，也可以是相对于设置文件的：

PLUGIN_PATHS = ["plugins", "/srv/pelican/plugins"]
PLUGINS = ["assets", "liquid_tags", "sitemap"]

2 在哪儿下载插件¶

新的命名空间插件可以在GitHub的 pelican-plugins 组织中找到，每个插件都是一个独立的仓库。而老的插件则可以在GitHub的 pelican-plugins 仓库中找到。这些老的插件会逐步淘汰并转移到新的命名空间版本。

pelican-extract-toc¶

pelican显示markdown时，将toc展示出来

# 在老系统中，需要手动clone
git clone  https://github.com/getpelican/pelican-plugins
pip install beautifulsoup4 # 安装依赖

双语插件¶

在新仓库中，直接使用pip安装

pip install pelican-i18n-subsites

主题¶

1.下载主题¶

git clone https://github.com/getpelican/pelican-themes

# 只下载 Elegant 这个主题。
git submodule update --init elegant

# 如果想下载所有主题，速度有点慢：
git submodule update --init --recursive
# 或者一开始就：
git clone --recursive https://github.com/getpelican/pelican-themes

2.配置主题¶

在pelicanconf.py中配置THEME = "pelican-themes/elegant"

评论¶

elegant主题有内置评论系统Utterances。只要在在 pelicanconf.py 中加入 Utterances 配置，文章页会加载评论组件。publishconf.py 会继承这些设置，发布时无需再改。

# Comments (Utterances → GitHub Issues: Feng-Zhang/blog-pelican-comment)
UTTERANCES_REPO = "Feng-Zhang/blog-pelican-comment"
UTTERANCES_THEME = "github-light"
COMMENTS_INTRO = "欢迎留言，使用 GitHub 账号登录即可评论。"

你还需要在 GitHub 上完成这几步（否则评论区会空白或报错）：

确认 Feng-Zhang/blog-pelican-comment 是公开仓库
在仓库 Settings → General → Features 里开启 Issues
打开 https://utteranc.es/，安装 Utterances GitHub App，并授权该仓库完成后重新部署网站，打开任意文章页，点击 Comments 折叠区即可看到评论框。

可选设置：某篇文章不想开评论，在 front matter 里加 comments: false 深色主题可改 UTTERANCES_THEME = "github-dark" 关闭某篇评论：utterances_filter: on（需同时设 UTTERANCES_FILTER = True）

小结¶

实践过程中，通过上面的设置我可以得到一个还不错的网站。但是想要把网站修改成自己想要的样式，还是需要个性化写一些html的配置。喜欢折腾的朋友可以借助 vibe coding 的工具进行修改。

参考资料¶

Pelican document： https://docs.getpelican.com/en/latest/
pelican github: https://github.com/getpelican/pelican
pelican主题：https://github.com/getpelican/pelican-themes

免费创建个人静态网站最佳实践：hugo+github+netlify

2020-05-25T10:20:00+08:00

[toc]

一、前言¶

关于搭建一个博客或个人网站的好处不用我多说，但创建网站的难度可能会让人望而却步。本人从网络上获得过很多帮助，学到很多。很早就萌发了自己建网站并分享知识的想法，但是又不想在简书这类的网站上写作。原谅我是个拖延控，有时间就写一点，很可能一篇文章写好久，也不喜欢在网上编辑。此外，知识需要积累形成框架，由于平时我所有的笔记都放在有道云笔记中，复制粘贴到简书有时候格式不对，又不想进行二次编辑。最重要的是不够Geek（装逼）。

其实中间有过一段时间，利用hexo、github和github page创建过静态网站。但是用得不太顺手，原因有很多，比如：老是花时间在怎么改网页主题上，而不是专注在写作上；markdown（md）文件中的图片迁移很麻烦，网上的图片老是会丢失；github page 在国内打开很慢而且SEO不容易搜索到。因此，一直耽误到现在，但一直贼心不死，想得到一个不太需要维护，可以专注写作，文档可以同步（在别的电脑上也可以编辑），又很geek的网站。我的想法是把所有笔记保存在有道云笔记中进行维护和整理，需要分享的话可以在本地用typora写md文档。此外，md文档中的图片用图床解决移动问题，然后托管到git自动渲染成网页。这样只要图床不挂，分享或上传到其它平台就很方便，因为只要复制md文档就行。为什么不直接用有道云笔记中的md呢？因为插入图片得是VIP才行，而导出来的md文档里所有图片的超链接是私人链接，移到别的地方根本没办法显示图片。最终我觉得搭网站最好的方式是：hugo+github+Netlify。适合我的笔记保存和写作的最佳方式是：有道云笔记+typora+picgo。如果觉得太麻烦了，不想把博客和有道云笔记等之类的笔记工具连接在一起，也不会传到其它平台上，可以直接用typora写作，利用hugo的page bundle绑定图片。

关于利用hugo和Github建网站的博客很多，但是有些博客内容有些出入，可能是由于英文翻译或版本更新所造成的。这里建议大家直接看hugo的英文官网和hugo in action，或者官方翻译。此外，网上的博客可以进行参考。这篇博客主要针对搭建过程中可能遇到的问题进行记录，希望对大家有所帮助。

二、原理¶

那么如何用静态网页创建网站呢？很多博客一上来就直接讲方法，怎么一步步运行，得到一个简陋的网页。但是不知其所以然，因此这里想先介绍一下基本原理，方便理解和后面的debug。

首先你得在本地生成静态网页文件。这里推荐用hugo或hexo。
然后把静态网页文件托管到github仓库。这里推荐使用git和gitlab工具。
把远程的静态网页文件进行渲染，形成让大家可根据网址直接阅览的网页。可用github page和Netlify.
找到有道云笔记的md文件，用typora进行编辑，并用图床解决图片容易丢失问题。

关于hugo和hexo，github和gitlab，github page和Netlify的差别网上有很多博客，这里就不赘述了。目前我觉得最好的方式是：hugo+github+Netlify。

三、快速入门¶

如果有相关静态网页生成的经历，可以直接忽略快速入门，直接到下一节：进阶。

1、本地生成静态网页文件¶

如果不想看英文的，可以参考这篇和这篇中文入门。

下面简要阐述过程：

hugo new site hugo #建立站点以后，博客根目录下默认有这些文件和子目录：archetypes/  config.toml  content/     data/        layouts/     static/      themes/
cd hugo
git init
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke # 安装主题
echo 'theme = "ananke"' >> config.toml
hugo new posts/my-first-post.md
hugo server

这时出现类似下面的信息，说明生成静态网页成功。可以在浏览器上输入 http://localhost:1313/ 进行浏览。

Building sites …
                   | EN
-------------------+-----
  Pages            | 11
  Paginator pages  |  0
  Non-page files   |  1
  Static files     | 39
  Processed images |  0
  Aliases          |  2
  Sitemaps         |  1
  Cleaned          |  0

Built in 37 ms
Watching for changes in E:\blogs\hugo\{archetypes,content,data,layouts,static,themes}
Watching for config changes in E:\blogs\hugo\config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

如果出现下面的错误：

hugo new posts/my-first-post.md
Error: "E:\blogs\quickstart\config.toml:3:1": unmarshal failed: Near line 3 (last key parsed ''): bare keys cannot contain '\x00'

这是因为E:\blogs\hugo\config.toml里面有一些NUL的间隔符，可能是由于echo的命令产生的。手动把它们删除就行了。

2、托管到github¶

把我们本地生成的静态网页托管到github上进行保存，而不用自己进行维护。首先在github上新建账号，并创建一个新的仓库，以仓库名为test为例。再下载安装git 。

cd .\public
git init
git add .
git commit -m "update"
git remote add origin https://github.com/你的git账户/test.git
git push origin master:master

这样就把东西上传到github上了。

为了方便发布网页，可以写成一个脚本，然后每次发布只要右键选择git bash here后运行./deploy.sh就可以。

#!/bin/bash

echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"

# build the project
hugo
git add .

msg="rebuilding site `date`"

if [ $# -eq 1 ]
  then msg="$1"
fi

git commit -m "$msg"

# push source to github
git push origin master:master

3、用Netlify渲染网页¶

如果要求不高，可以直接用Github Pages进行托管。但是Github在国内打开速度很慢，所以建议用Netlify对托管到github上的静态网页进行布署。很简单，可以看这篇教程。至此一个简陋的网页就建好了。记得改一下Netlify自动分配给你的域名，不过只能更改前缀。要求不高也还好了。下面简单描述一下操作步骤：

用github的账号登陆Netlify。
点击右上角的Create new site
跳转到第一步，connect to git provider，选github
pick a repository，选择存放代码的仓库。
Build options and deploy。点击Deploying就ok了。
等待一会配置，就会出现网址了。类似这样的https://priceless-morse-029791.netlify.app。
复制粘贴网址就大功告成。

目前我们可以以网站形式来展示内容，但是初始化的见面一点也不cool啊。客官别急，请看下面进阶教程。

四、进阶¶

1、添加主题¶

首先我们可以到hugo主题库中找一个自己喜欢的主题。我比较喜欢的一个主题是academic，B站上还有人介绍Academic视频。由于大部分主题都已经有站点所需要的各种文件夹，所以不用自己再建站点。直接clone下来，把主题换成子模块的就行。快速入门的什么的可以忘记了^_^。

git clone https://github.com/sourcethemes/academic-kickstart.git My_Website
cd My_Website
git submodule update --init --recursive

2、修改网页布局¶

我们可以根据academic文档进行修改，变成你自己喜欢的样式。这个academic帮助文档讲得很清楚，这里就不赘述。

不过这里提一下添加评论系统，这应该是一个刚需。要不然没有互动在那孤芳自赏？

由于academic主题设置commento很方便，这里图方便直接用了：

把config/_default/params.toml中的engine = 0改成engine = 2。
~~注册commento账号，把你自己博客域名进行绑定即可。~~ commento后来发现是收费的，现改成valine。
valine的加载有点麻烦，可以参考博客。此外，国外用的比较多的有Disqus，国内有valine和Gittalk。不过Gitalk有点复杂，可参考这篇博客进行安装。

五、写作¶

1、图片管理¶

在md文档中插入的图片是一个麻烦事。一般来说有三种解决方案。如下所示

放置在static中¶

可以直接把图片放在static中，不过以后图片一多就麻烦了。如果后面想迁移什么的就太麻烦了。

利用page bundle¶

可以在post下面新建文件夹，重命名为你想要的博客名后新建md文件。这个md文档名称一定得是index.md，然后我们就可在同一目录下放置图片。md可以使用相对位置进行引用。

其实如果不是为了在有道云笔记中同时显示md文件中的图片，这种方式是最方便的，而且免费。

利用图床¶

这里利用picgo工具，把图片复制后，按一个快捷键就会自动上传到picgo内设置的图床上。

picgo教程支持8大图床。可以选免费的smms和github（虽然github慢了点），也可以氪金买云服务。

同时typora还支持picgo的插件，直接复制图片就可以实现上传到云端。不过配置可能会遇到些问题，可以参考这篇博客排坑。

综上，图床是最方便的，但需要点时间配置各个软件。page bundle是最简单的，但是如果没法移动到其它平台。

2、更新博客的流程¶

日后更新博客时就只需要在本地的hugo\content\post文件夹中编辑新的md文件，然后./deploy.sh就会自动编译静态网页然后上传至github，同时Netlify会检测Github中库的动态，并及时更新发布的网站内容。

3、在另一台电脑上写作¶

由于静态网页是托管到github，可以很方便地进行同步。直接用git pull把github拉下来就行，写完后git push 到仓库就万事大吉了。

以上就是免费创建个人静态网站地最佳实践。全免费，渲染快捷且可以专注写作，不用费心维护。

六、域名¶

最后为了装一下，怎么也得换个个性化的域名啊。网上到处看了看，感觉比较复杂。因为在国内买域名还得备案，听说很麻烦。后来直接到name.com购买了域名。用了一段时间后，发现有点贵，最后转到阿里云买域名。

域名解析¶

可以参考这篇博客。部署成功，Netlify会自动分配一个随机的域名给你。我们可以自行修改成方便记忆的，比如我这里使用的fengbuzhi.netlify.app。但是这个域名太长了，因此可以设置自定义域名。

登陆netlify。选择相对应的网站。
绑定域名。Domain settings-Add custom domain - 输入完整域名-保存。这时会出现一个警告，Check DNS configuration，这是因为这时还没有被域名服务商解析。
解析域名。登陆自己域名的服务商网站，这里以阿里云为例，添加一条CNAME解析。
域名列表-找到域名并在域名右边点击解析设置
在打开的窗口点击添加记录记录类型：选择CNAME 主机记录：默认@，若要需要www访问可再添加一个解析路线：默认记录值：netlify中的默认域名（我的是fengbuzhi.netlify.app，请用自己的，否则将连到我的站点） TTL：默认
生成HTTPS证书，实现HTTPS访问。Domain settings-Verify DNS configuration-确定

值得注意的是：你也可以增加A记录，解析IP地址。这是由netlify提供的，可过ping fengbuzhi.netlify.app来得到。但是有个疑问这个IP地址每次ping得到的都不一样，不知道什么意思？此外，在你的域名购买商处管理DNS的时候，要加两条DNS。一条是没有www，一条是有www。阿里云会自动添加，但在name服务商中需要手动添加。

七、Debug¶

push error

git push academic master
remote: Permission to Feng-Zhang/academic-kickstart.git denied to xiaofeng007.
fatal: unable to access 'https://github.com/Feng-Zhang/academic-kickstart.git/': The requested URL returned error: 403

控制面板-用户帐户-凭据管理器-找到git:https://github.com-编辑对这个凭据进行编辑，把要远程的账号和密码加上。