搭建静态博客的工具多种多样,即有流行的WordPress,也有 因为我本人对
本文主要涉及 1. 准备环境选定工作目录,并使用pipenv创建一个虚拟环境:
在虚拟环境中安装必要的包:
2. 新建项目
它在执行的过程中,会交互式的询问一些配置项,如果你现在还不能确定的话,那就大胆的使用默认值吧,后面还可以在配置文件中修改; 命令执行完成后,它会在我们的项目中新建如下的目录和文件:
其中,
3. 第一篇博文现在我们在
4. 修改配置文件在正式开始构建之前,我们需要完善一下配置文件
5. 本地构建和访问我们通过以下命令构建网站并自动适配文件的修改,通过http://localhost:8000访问:
6. |
扩展 | 文档 | 描述 |
---|---|---|
Abbreviations | https://python-markdown./extensions/abbreviations/ | |
Attribute Lists | https://python-markdown./extensions/attr_list/ | |
Definition Lists | https://python-markdown./extensions/definition_lists/ | |
Fenced Code Blocks | https://python-markdown./extensions/fenced_code_blocks/ | 扩展了代码块的写法 |
Footnotes | https://python-markdown./extensions/footnotes/ | |
Tables | https://python-markdown./extensions/tables/ | 支持表格 |
我们重点看一下Fenced Code Blocks
,因为它支持了我常用的三个反引号包裹代码块的写法:
GitHub‘s backtick (```) syntax is also supported:
# more python code
然后,我们再看一下markdown.extensions.codehilite扩展:
它基于Pygments包为我们提供了代码的高亮显示,我们主要看一下它的一些可配置选项:
linenums
:如果置为True
,将会为代码块每行标上行号;
css_class
:为<div>
标签加上class
属性,默认是codehilite
;在这里,pelican
使用的是highlight
;
最后,我们看一下markdown.extensions.meta:
它主要是pelican
内部使用,还记得我们每个markdown
文本的开头都要有特定的格式吗?就是通过这个扩展读取的;感兴趣的同学可以自己去看一下,这里我们就不多说了;
看到现在,我们也没有找到想要的解决方案:对列表里缩进嵌套反引号包裹的代码块,进行正确的渲染;
还好我们还有众多的第三方扩展供我们使用:https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions
我们找到一个pymdownx.extra的扩展貌似可以代替markdown.extensions.extra
,来一起看一下吧:
它和markdown.extensions.extra
大部分是一样的,只是有以下不同:
新包含了BetterEm扩展:优化粗体和斜体的展示(不关心);
新包含了ExtraRawHTML扩展:增加了对原始HTML
代码的处理(不关心);
使用SuperFences扩展代替Fenced Code Blocks
:加强版的markdown
语法解析(看来正式我们想要的);
其实,看到
SuperFences
文档的第一句话,我就知道妥了,嘻嘻;Allowing the nesting of fences under blockquotes, lists, or other block elements (see Limitations for more info).
文档的内容很丰富,我们就不再这里一一解释了,有兴趣的同学可以自己去看一看,说不定有什么意外的收获呢!!!
现在,我们来实际解决这个问题:
安装必要的包:
λ pipenv install pymdown-extensions
修改pelicanconf.py
文件中MARKDOWN
的默认配置:
# 使用第三方扩展来增强对 markdown 语言的解析,但是首先要安装 pymdown-extensions 模块MARKDOWN = { 'extension_configs': { 'markdown.extensions.codehilite': {'css_class': 'highlight'}, 'pymdownx.extra': {}, 'markdown.extensions.meta': {},
}, 'output_format': 'html5',
}
我在浏览SuperFences
文档时,发现一个很有意思的章节:https://facelessuser./pymdown-extensions/extensions/superfences/#code-highlighting;
它推荐了pymdownx.highlight代替markdown.extensions.codehilite
,那我们就来看看这到底是个什么鬼?
在它的文档中有一句话大概能说明两者的关系:
The Highlight extension is inspired by CodeHilite, but differs in features. PyMdown Extensions chooses not to implement special language headers for standard Markdown code blocks like CodeHilite does; PyMdown Extensions takes the position that language headers are better suited in fenced code blocks.
更多实现上的细节,我们不再去深究,主要看看我们可以用来干什么?
比如,为代码块每行加上行号:
咦?markdown.extensions.codehilite
也可以啊,它不是也有一个linenums
的选项吗?置成True
不就行了;
说的对,不过丑。
一般情况下,为代码块添加行号有两种样式:
table
:默认的样式,创建一个表,第一列是行号;
inline
:在每行代码的开头,但是复制代码会把行号一起复制,不方便;
不过,pymdownx.highlight
提供了第三种样式:pymdownx-inline
,它和inline
很像,只是复制时不会加上行号,因为实际上把行号元素渲染成下面这样:
<span class="lineno" data-linenos="1 "></span>
然后,我们通过以下的CSS
样式去“激活”它:
[data-linenos]:before { content: attr(data-linenos);
}
下面,我们来将它具体的应用到我们的项目中吧:
首先,修改pelicanconf.py
文件中MARKDOWN
的默认配置:
# 使用第三方扩展来增强对 markdown 语言的解析,但是首先要安装 pymdown-extensions 模块MARKDOWN = { 'extension_configs': { 'pymdownx.highlight': { 'css_class': 'highlight', 'linenums': True, 'linenums_style': 'pymdownx-inline',
}, 'pymdownx.extra': {}, 'markdown.extensions.meta': {},
}, 'output_format': 'html5',
}
然后,在output/theme/css/main.css
文件的末尾加上下面这段代码:
[data-linenos]:before { content: attr(data-linenos);
}
最后重启下服务,就能看到效果了:
注意:
这里有个问题,如果我们重新执行构建命令,
output/theme/css/main.css
文件又会被覆盖成原先的内容,我们这个效果就看不到了;不过这并不是我们最终的方案,所以我们也不在这里继续深究了。
|