table of Contents
We have successfully built a local blog site, it uses pelican
the default notmyidea
theme;
If you do not remember, you can look at this article: First, build your own from scratch static blog - Basics ;
In fact, pelican
with many open-source library theme, we can pelican
theme warehouse choose one of their favorite theme to the project;
http://pelicanthemes.com/ sites are available online preview of the theme;
I chose the pelican-alchemy themes, its online Demo
are: https://nairobilug.github.io/pelican-alchemy/ ;
Now, let's step by step to apply it to our project;
1. Download Theme
I was glancing through a bit pelican-alchemy
of documents and issue
lists, taking into account the follow-up is likely to make some changes, so I decided it first fork
to its own warehouse;
Then, I created a directory in the project root directory themes/
for storing all downloaded themes, and then fork
after pelican-alchemy
as a separate sub-cloned into the warehouse catalog:
λ mkdir themes
λ git submodule add [email protected]:luizyao/pelican-alchemy.git themes/pelican-alchemy
note:
git submodule add <url> <path>
Command is to add a warehouse to the specified directory as a separate sub-warehouse;If you look closely, you will find more than one file at our root:
.gitmodules
it records the information sub-warehouse;For example: the contents of this document in our program are:
[submodule "themes/pelican-alchemy"] path = themes/pelican-alchemy url = [email protected]:luizyao/pelican-alchemy.git
Operations related to common and there are several sub-warehouse the following:
When cloning parent warehouse, along with sub-cloning warehouse together:
git clone --recurse-submodules <URL> <directory>
View the status of all sub-parent warehouse warehouse:
λ git submodule status 3381c5031bf30d3b1212619b662898f178d695f1 themes/pelican-alchemy (v2.1-43-g3381c50)
3381c5031bf30d3b1212619b662898f178d695f1
It is currentlyCommit Id
theSHA-1
encrypted string;Delete sub Warehouse:
git rm <submodule path> && git commit
And then manually delete the
.git/modules/<name>/
directoryIf you want to know more about the
git submodule
content, you cangit submodule --help
read its official documentation;
2. Using themes
2.1. Basic Configuration
# pelicanconf.py
# 主题所在的相对目录
THEME = 'themes/pelican-alchemy/alchemy'
# 副标题
SITESUBTITLE = '戒骄戒躁 砥砺前行'
# 头像
SITEIMAGE = '/images/profile.png width=200 height=200'
# 友链
LINKS = (
('pytest-chinese-doc', 'https://luizyao.github.io/pytest-chinese-doc/'),
)
# 代码高亮的样式
PYGMENTS_STYLE = 'friendly'
# 使用 Bootswatch 样式:https://bootswatch.com/
BOOTSTRAP_CSS = 'https://cdn.bootcss.com/bootswatch/4.3.1/lux/bootstrap.min.css'
# 生成 sitemap.xml 文件,它是一个对爬虫友好的文件,方便搜索引擎抓取网站页面
DIRECT_TEMPLATES = ['index', 'tags', 'categories', 'authors', 'archives', 'sitemap']
SITEMAP_SAVE_AS = 'sitemap.xml'
# 构建后的 html 文件路径和 URL 标识
ARTICLE_URL = 'posts/{date:%Y}/{date:%m}/{slug}.html'
ARTICLE_SAVE_AS = ARTICLE_URL
DRAFTS_URL = 'drafts/{date:%Y}/{date:%m}/{slug}.html'
DRAFTS_SAVE_AS = ARTICLE_URL
PAGE_URL = 'pages/{slug}.html'
PAGE_SAVE_AS = PAGE_URL
# RSS 订阅
FEED_ALL_RSS = 'feeds/all.rss.xml'
Details can refer to: https://github.com/nairobilug/pelican-alchemy/wiki/Settings
2.2. Advanced Configuration
2.2.1. Configure site icon
Through online tools https://realfavicongenerator.net/ can be adapted to generate a variety of platforms and browsers favicon
file:
Download generated above the favicon
pack and unpack into the project content/extras
directory:
λ ls content/extras/
android-chrome-192x192.png favicon.ico safari-pinned-tab.svg
android-chrome-384x384.png favicon-16x16.png site.webmanifest
apple-touch-icon.png favicon-32x32.png
browserconfig.xml mstile-150x150.png
Modify the template base.html
file:
<!-- themes/pelican-alchemy/alchemy/templates/base.html -->
{% if RFG_FAVICONS %}
<link rel="apple-touch-icon" href="{{ SITEURL }}/apple-touch-icon.png" sizes="180x180">
<link rel="icon" type="image/png" href="{{ SITEURL }}/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="{{ SITEURL }}/favicon-16x16.png" sizes="16x16">
<link rel="manifest" href="{{ SITEURL }}/manifest.json">
<meta name="theme-color" content="#333333">
{% endif %}
<!-- 改成 -->
{% if RFG_FAVICONS %}
<link rel="apple-touch-icon" href="{{ SITEURL }}/apple-touch-icon.png" sizes="180x180">
<link rel="icon" type="image/png" href="{{ SITEURL }}/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="{{ SITEURL }}/favicon-16x16.png" sizes="16x16">
<link rel="manifest" href="{{ SITEURL }}/site.webmanifest">
<link rel="mask-icon" href="{{ SITEURL }}/safari-pinned-tab.svg" color="#5bbad5">
<meta name="msapplication-TileColor" content="#da532c">
<meta name="theme-color" content="#ffffff">
{% endif %}
Modify pelicanconf.py
the configuration file:
# pelicanconf.py
# 在构建中,它们会无损的拷贝到 output 的同名目录下
STATIC_PATHS = ['extras', 'images', 'css']
# 构建时,extras/android-chrome-192x192.png文件,拷贝到output/android-chrome-192x192.png,不再是output/extras/android-chrome-192x192.png
EXTRA_PATH_METADATA = {
'extras/android-chrome-192x192.png': {'path': 'android-chrome-192x192.png'},
'extras/android-chrome-512x512.png': {'path': 'android-chrome-512x512.png'},
'extras/apple-touch-icon.png': {'path': 'apple-touch-icon.png'},
'extras/browserconfig.xml': {'path': 'browserconfig.xml'},
'extras/favicon-16x16.png': {'path': 'favicon-16x16.png'},
'extras/favicon-32x32.png': {'path': 'favicon-32x32.png'},
'extras/favicon.ico': {'path': 'favicon.ico'},
'extras/manifest.json': {'path': 'manifest.json'},
'extras/mstile-150x150.png': {'path': 'mstile-150x150.png'},
'extras/safari-pinned-tab.svg': {'path': 'safari-pinned-tab.svg'},
# 自定义样式
'css/custom.css': {'path': 'theme/css/custom.css'},
}
# 自定义样式的URL目录
THEME_CSS_OVERRIDES = ('theme/css/custom.css',)
RFG_FAVICONS = True
2.2.2 Update Font Awesome
version
pelican-alchemy
Use Font Awesome 4.7.0
version, and you are using relative references static resources;
We will modify it to the latest 5.11.2
version of CDN
the introduction, modify the theme templates of base.html
documents:
<!-- themes/pelican-alchemy/alchemy/templates/base.html -->
<link rel="stylesheet" href="{{ SITEURL }}/theme/css/font-awesome.min.css">
<!-- 改成 -->
<link href="https://cdn.bootcss.com/font-awesome/5.11.2/css/fontawesome.min.css" rel="stylesheet">
<link href="https://cdn.bootcss.com/font-awesome/5.11.2/css/solid.css" rel="stylesheet">
<link href="https://cdn.bootcss.com/font-awesome/5.11.2/css/brands.css" rel="stylesheet">
In addition to the above steps, we have an additional job to do: Since 5.x
version no longer use fa
the prefix and replace it fas
( Solid
style ) and fab
( Brands
styles );
So, for those of a similar theme in class="fa fa-github"
the style it should be amended to class="fab fa-github"
, mainly related to article.html
, index.html
and header.html
these documents;
Finally, modify the pelicanconf.py
document on the ICONS
format of the configuration, you need to specify additional style categories:
# pelicanconf.py
# 社交属性,请到<https://fontawesome.com/icons>网站确定图标样式的类别
ICONS = [
('fab', 'github', 'https://github.com/luizyao'),
('fas', 'blog', 'https://www.cnblogs.com/luizyao/'),
('fas', 'rss', 'feeds/all.rss.xml')
]
pelican-alchemy
There is aopen
ofissue
: https://github.com/nairobilug/pelican-alchemy/issues/69 about theFont Awesome
version, follow-up may be updated to5.x
version, currentlyissue
in a state of receiving feedback;As for why not to use
CDN
, looks great and is also related to the firewall it. . .I'm sure you've heard of the Great Firewall of China; India, Russia, some African countries are doing similar things. You never know which URL or IP might become inaccessible
2.2.3 The use of Bootstrap
style
We can add elements to a particular type of Bootstrap
official style; for example: for each img
added element of class = "img-fluid"
style;
First, install dependencies:
# beautifulsoup4为插件所依赖的第三方包
λ pipenv install beautifulsoup4
Then, download Bootstrapify plug-ins:
λ mkdir plugins
λ git submodule add [email protected]:ingwinlu/pelican-bootstrapify.git plugins/pelican-bootstrapify
Finally, modify pelicanconf.py
the configuration file:
# 到哪里寻找插件
PLUGIN_PATHS = ['plugins']
# 想要使用的插件名
PLUGINS = ['pelican-bootstrapify']
# 想要添加的 Bootstrap 样式
BOOTSTRAPIFY = {
'table': ['table', 'table-striped', 'table-hover'],
'img': ['img-fluid'],
}
2.3 Custom Theme
Here we pelican-alchemy
do some customization of operation, add some new features;
2.3.1. Adding a link back to top
Modified base.html
file, <head>
add the following components:
<!-- themes/pelican-alchemy/alchemy/templates/base.html -->
<script src="https://cdn.bootcss.com/jquery/3.4.1/jquery.min.js"></script>
<script src="https://cdn.bootcss.com/scrollup/2.4.1/jquery.scrollUp.min.js"></script>
<script>
$(function () {
$.scrollUp({
scrollText: '<i class="fas fa-2x fa-chevron-circle-up"></i>'
});
});
</script>
2.3.2. Support Directory
I wrote a plugin that replaces pelican
the default MarkdownReader
, it has the following features:
Using enhanced
markdown
parsing- pymdownx.extra place
markdown.extensions.extra
; - pymdownx.highlight place
markdown.extensions.codehilite
;
- pymdownx.extra place
It supports the following ways to generate article directories:
In
markdown
the text[TOC]
mark generating directory;Through metadata
toc
custom directory styles; for example:{% if article.toc %} <aside class="col-md-4"> <div class="widget widget-content"> <h3 class="widget-title">文章目录</h3> <div class="toc"> <ul> {{ article.toc | safe }} </ul> </div> </div> </aside> {% endif %}
If you do not fit
summary
orsummary
is empty, it supports automatic interception of the beginning of the character as a summary;
Instructions:
As a sub-warehouse download
# 项目根目录创建目录 λ mkdir plugins # 下载 λ git submodule add [email protected]:luizyao/pelican-md-reader.git plugins/pelican-md-reader
Modify
pelicanconf.py
the configuration file# pelicanconf.py # 到哪里寻找插件 PLUGIN_PATHS = ['plugins'] # 想要使用的插件名 PLUGINS = ['pelican-md-reader']
For more details refer to: Pelican-md-Reader
2.3.3. Speaking
The main keyword finished;
3. Complete pelicanconf.py
file
#!/usr/bin/env python
# -*- coding: utf-8 -*- #
from __future__ import unicode_literals
AUTHOR = 'luizyao'
SITENAME = "luizyao's blog"
SITEURL = ''
PATH = 'content'
DEFAULT_LANG = 'en'
# Feed generation is usually not desired when developing
FEED_ALL_ATOM = None
CATEGORY_FEED_ATOM = None
TRANSLATION_FEED_ATOM = None
AUTHOR_FEED_ATOM = None
AUTHOR_FEED_RSS = None
DEFAULT_PAGINATION = 10
# Uncomment following line if you want document-relative URLs when developing
# RELATIVE_URLS = True
# 修改时区
TIMEZONE = 'Asia/Shanghai'
# 修改默认的时间格式('%a %d %B %Y')
DEFAULT_DATE_FORMAT = "%Y-%m-%d %H:%M"
# 为元数据定义默认值
DEFAULT_METADATA = {
# 默认发布的文章都是草稿,除非在文章元数据中明确指定:Status: published
'status': 'draft',
}
# pelican-alchemy 原有的配置
# 主题所在的相对目录
THEME = 'themes/pelican-alchemy/alchemy'
# 副标题
SITESUBTITLE = '戒骄戒躁 砥砺前行'
# 头像
SITEIMAGE = '/images/profile.png width=200 height=200'
# 友链
LINKS = (
('pytest-chinese-doc', 'https://luizyao.github.io/pytest-chinese-doc/'),
)
# 代码高亮的样式
PYGMENTS_STYLE = 'friendly'
# 使用 Bootswatch 样式:https://bootswatch.com/
BOOTSTRAP_CSS = 'https://cdn.bootcss.com/bootswatch/4.3.1/lux/bootstrap.min.css'
# 生成 sitemap.xml 文件
DIRECT_TEMPLATES = ['index', 'tags', 'categories', 'authors', 'archives', 'sitemap']
SITEMAP_SAVE_AS = 'sitemap.xml'
# 构建后的 html 文件路径和 URL 标识
ARTICLE_URL = 'posts/{date:%Y}/{date:%m}/{slug}.html'
ARTICLE_SAVE_AS = ARTICLE_URL
DRAFTS_URL = 'drafts/{date:%Y}/{date:%m}/{slug}.html'
DRAFTS_SAVE_AS = ARTICLE_URL
PAGE_URL = 'pages/{slug}.html'
PAGE_SAVE_AS = PAGE_URL
# RSS 订阅
FEED_ALL_RSS = 'feeds/all.rss.xml'
# 在构建中,它们会无损的拷贝到 output 的同名目录下
STATIC_PATHS = ['extras', 'images', 'css']
# 构建时,extras/android-chrome-192x192.png文件,拷贝到output/android-chrome-192x192.png,不再是output/extras/android-chrome-192x192.png
EXTRA_PATH_METADATA = {
'extras/android-chrome-192x192.png': {'path': 'android-chrome-192x192.png'},
'extras/android-chrome-512x512.png': {'path': 'android-chrome-512x512.png'},
'extras/apple-touch-icon.png': {'path': 'apple-touch-icon.png'},
'extras/browserconfig.xml': {'path': 'browserconfig.xml'},
'extras/favicon-16x16.png': {'path': 'favicon-16x16.png'},
'extras/favicon-32x32.png': {'path': 'favicon-32x32.png'},
'extras/favicon.ico': {'path': 'favicon.ico'},
'extras/manifest.json': {'path': 'manifest.json'},
'extras/mstile-150x150.png': {'path': 'mstile-150x150.png'},
'extras/safari-pinned-tab.svg': {'path': 'safari-pinned-tab.svg'},
# 自定义样式
'css/custom.css': {'path': 'theme/css/custom.css'},
}
# 自定义样式的URL目录
THEME_CSS_OVERRIDES = ('theme/css/custom.css',)
RFG_FAVICONS = True
# 到哪里寻找插件
PLUGIN_PATHS = ['plugins']
# 想要使用的插件名
PLUGINS = ['pelican-bootstrapify', 'pelican-md-reader']
# 想要添加的 Bootstrap 样式
BOOTSTRAPIFY = {
'table': ['table', 'table-striped', 'table-hover'],
'img': ['img-fluid'],
}
# 社交属性,请到<https://fontawesome.com/icons>网站确定图标样式的类别
ICONS = [
('fab', 'github', 'https://github.com/luizyao'),
('fas', 'blog', 'https://www.cnblogs.com/luizyao/'),
('fas', 'rss', 'feeds/all.rss.xml')
]