pelican学习笔记（二）之Writing content

最新推荐文章于 2023-11-22 00:20:49 发布

Justin-x

最新推荐文章于 2023-11-22 00:20:49 发布

阅读量983

点赞数 1

分类专栏：学习笔记 pelican 文章标签： pelican 建站

本文链接：https://blog.csdn.net/oschina_41552937/article/details/79162067

版权

学习笔记同时被 2 个专栏收录

6 篇文章 0 订阅

订阅专栏

pelican

4 篇文章 0 订阅

订阅专栏

这篇博客介绍了Pelican的内容创作过程，包括文章与页面的区别、文件元数据、内部链接、页面处理、翻译支持以及语法高亮等功能，强调了链接到内部内容、静态文件和附件的方法，适合Pelican用户参考。

摘要由CSDN通过智能技术生成

学习http://docs.getpelican.com/en/stable/content.html时做非精准翻译，权当笔记
前文见pelican学习笔记之GITHUB建站(一)

Writing content

2018/01/25

Articles and pages 文章和页面

Pelican 认为 “文章(articles)” 是按时间顺序排列的内容, 如博客上的帖子, 因此与日期相关。

“页面(pages)” 背后的想法是, 它们通常不是时态性质的, 用于不经常更改的内容 (例如, “关于” 或 “联系” 页面)。

你可以在官方库中找到一些例子在https://github.com/getpelican/pelican/tree/master/samples/content

File metadata 文件中的信息

Pelican 尽可能的自己从文件系统得到信息（如，关于文章的类别，当不指定时pelican会使用文件夹作为分类依据），但是你仍需要在文件中提供一些信息(metadata)。

如果您以 reStructuredText 格式编写内容, 则可以通过以下语法在文本文件中提供此信息 (以 . rst后缀名的文件):

My super title

#

:date: 2010-10-03 10:20
:modified: 2010-10-04 18:40
:tags: thats, awesome
:category: yeah
:slug: my-super-post
:authors: Alexis Metaireau, Conan Doyle
:summary: Short version for index and feeds

authors 和 tags 可以用分号（;）或逗号 (,) 分隔。

:tags: pelican, publishing tool; pelican, bird
:authors: Metaireau, Alexis; Doyle, Conan

Pelican 通过abbr标记实现了对 reStructuredText 的扩展, 以启用对 HTML 的支持。你可以在你的推送(post)中像这样写:

This will be turned into :abbr:HTML (HyperText Markup Language).

你同样可以使用 Markdown 语法（后缀名为 .md，.markdown，.mkd或.mdown）。Markdown生成器要求你先安装Markdown包，请尝试运行pip install Markdown命令。

Pelican 同时支持扩展的Markdown语法 (Markdown Extensions)，如果扩展语法没有包含在Markdown包中，可能需要另行安装。

Markdown 的文件需要像下面一样添加信息(metadata)：

Title: My super title
Date: 2010-12-03 10:20
Modified: 2010-12-05 19:30
Category: Python
Tags: pelican, publishing
Slug: my-super-post
Authors: Alexis Metaireau, Conan Doyle
Summary: Short version for index and feeds

This is the content of my super blog post.

其他格式（如 AsciiDoc）需要通过插件支持，请参与pelican-plugins的相关说明。

Pelican同样可以处理.html和.htm结尾的HTML文件。它以非常直接的方式读取信息，title从title，body从body：

<html>
    <head>
        <title>My super title</title>
        <meta name="tags" content="thats, awesome" />
        <meta name="date" content="2012-07-09 22:28" />
        <meta name="modified" content="2012-07-10 20:14" />
        <meta name="category" content="yeah" />
        <meta name="authors" content="Alexis Métaireau, Conan Doyle" />
        <meta name="summary" content="Short version for index and feeds" />
    </head>
    <body>
        This is the content of my super blog post.
    </body>
</html>

使用 html, 标准信息有一个简单的做法: tags可以按Pelican标准要求的通过tags标记指定, 也可以按HTML要求的通过keywords提供信息。两者可以互换使用。

请注意, 除了title之外, 本文的其他信息(metadata)都不是必需提供的: 如果未指定日期, 并且 DEFAULT_DATE 设置为 'fs', 则将依赖于文件的 “mtime” 时间戳, 并且该类别可以由文件所在的目录确定。例如, 位于 python/foobar/myfoobar. rst 的文件将有一个foobar类别。如果您想以其他方式组织文件, 而该文件夹的名称不是一个好的类别名称, 则可以将设置 USE_FOLDER_AS_CATEGORY 设置为 False。在分析页面信息给定的日期时, Pelican支持 W3C’s 建议的ISO 8601。

注意：
在尝试使用不同的设置 (特别是信息) 时, 缓存可能会发生干扰，使更改可能不可见。在这种情况下, 禁用缓存 LOAD_CONTENT_CACHE = False 或使用--ignore-cache命令行开关忽略缓存。

modified应是上次更新文章的时间, 如果未指定, 则默认为date。除了可以在模板中显示modified外, 当您修改文章后将midified设置为当前日期时, feed readers 中的提要条目将自动更新。

authors是一个逗号分隔的文章作者列表。如果只有一个作者可以使用author。

如果你没有在 post 中指定摘要信息, 则可以使用 SUMMARY_MAX_LENGTH 设置来指定从文章开头的多少单词用作摘要。

还可以通过在 FILENAME_METADATA 设置中设置的正则表达式从文件名中提取信息。所有匹配的命名组将在信息对象中设置。FILENAME_METADATA 设置的默认值仅从文件名中提取日期。例如, 如果您想提取日期和slug, 可以设置如下内容:'(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'

请注意, 文件中可用的信息优先于从文件名中提取的信息。

2018/01/26

Pages 页面

如果你在 content 文件夹下建立了一个叫pages的文件夹，所有在这个文件夹内的文件都会用来生成静态页面 ( static pages)，像 About 和 Contact 页面等。（看下面给出的例子。）

你可以使用设置 DISPLAY_PAGES_ON_MENU 来控制是否所有这些页面都显示在主导航菜单中。(默认值为 True。)

如果要关闭某个页面在菜单中链接或列出, 请添加status: hidden属性到其信息中。这对于制作适合网站主题的错误页面(error pages)非常有用。

Linking to internal content 内部链接

从 Pelican 3.1 开始, 现在可以指定站点内部链接 ( intra-site ) 到源内容层次 (source content hierarchy)结构中的文件, 而不是生成的层次 (generated hierarchy)结构中的文件。这使得从当前帖子 ( current post)链接到可能与该帖子并排的其他内容更容易 (而不必确定在站点生成之后其他内容的将放置位置)。

要链接到内部内容 (content目录中的文件), 请对链接目标使用以下语法: {filename}path/to/file，注: 正斜线（/）是所有操作系统 (包括 Windows) 的 {filename} 指令中的路径分隔符。

举例如下，加入有一个 Pelican 项目的结构像下面这样：

website/
├── content
│   ├── category/
│   │   └── article1.rst
│   ├── article2.md
│   └── pages
│       └── about.md
└── pelican.conf.py

其中article1.rst可能是这样：

The first article
#################

:date: 2012-12-01 10:02

See below intra-site link examples in reStructuredText format.

`a link relative to the current file <{filename}../article2.md>`_
`a link relative to the content root <{filename}/article2.md>`_

article2.md如下：

Title: The second article
Date: 2012-12-01 10:02

See below intra-site link examples in Markdown format.

[a link relative to the current file]({filename}category/article1.rst)
[a link relative to the content root]({filename}/category/article1.rst)

Linking to static files 链接到静态文件

像上文提到的使用{filename}标识来连接到既非 aritcle 也非 pages 的内容。必须记住, 这些文件不会被复制到output目录中, 除非包含它们的源目录包含在项目的 pelicanconf.py 文件的 STATIC_PATHS 设置中。Pelican 的配置默认包括images目录，但必须手动添加其他内容。忘记这样做会导致链接断开。

举例来说，一个项目又如下目录结构：

content
├── images
│   └── han.jpg
├── pdfs
│   └── menu.pdf
└── pages
    └── test.md

test.md中的链接：

![Alt Text]({filename}/images/han.jpg)
[Our Menu]({filename}/pdfs/menu.pdf)

pelicanconf.py文件设置如下：

STATIC_PATHS = ['images', 'pdfs']

网站生成的时候就会复制han.jpg到output/image/han.jpg，menu.pdf到output/pdfs/menu.pdf，并且添加正确的链接到test.md。

Mixed content in the same directory 同一文件夹下的混合内容

从 Pelican 3.5 开始, 静态文件可以安全地与页面源文件共享源目录, 而不会在生成的站点中公开页面源。任何此类目录都必须同时添加到 STATIC_PATHS 和 PAGE_PATHS (或 STATIC_PATHS 和 ARTICLE_PATHS)。Pelican 通常会识别和处理页面源文件, 并将其余的文件复制到为静态文件保留的单独目录中。

Note: 将静态和内容源文件放在同一个源目录中并不能保证它们最终会在生成的站点中的同一位置。为确保如此的最简单方法是使用 {attach} 链接语法 (参见下一节)。或者, 可以将 STATIC_SAVE_AS、PAGE_SAVE_AS 和 ARTICLE_SAVE_AS 属性 (以及相应的 * _URL 属性) 设置为将不同类型的文件放在一起, 就像在早期版本的 Pelican 中一样。

Attaching static files 附件

从 Pelican 3.5 开始, 静态文件(static files)可以使用{attach}path/to/file将目标 “附加” 到一个网页或文章上，这类似于 {filename} 语法, 但也将静态文件重新定位到链接文档的output目录中。如果静态文件源自链接文档源下的子目录, 则该关系将保留在输出上。否则, 它将成为链接文档的同级。

这只适用于链接到静态文件, 而且仅当它们源自于 STATIC_PATHS 属性中包含的目录时。

举个栗子，如下的目录结构：

content
├── blog
│   ├── icons
│   │   └── icon.png
│   ├── photo.jpg
│   └── testpost.md
└── downloads
    └── archive.zip

pelicanconf.py设置如下：

PATH = 'content'
STATIC_PATHS = ['blog', 'downloads']
ARTICLE_PATHS = ['blog']
ARTICLE_SAVE_AS = '{date:%Y}/{slug}.html'
ARTICLE_URL = '{date:%Y}/{slug}.html'

testpost.md内容如下：

Title: Test Post
Category: test
Date: 2014-10-31

![Icon]({attach}icons/icon.png)
![Photo]({attach}photo.jpg)
[Downloadable File]({attach}/downloads/archive.zip)

生成器生成的output目录结构如下：

output
└── 2014
    ├── archive.zip
    ├── icons
    │   └── icon.png
    ├── photo.jpg
    └── test-post.html

请注意, 所有使用 {attach} 链接的文件最终都在文章的输出目录中或下面。

如果静态文件 ( static file )被多次链接, 则 {attach} 的重新定位功能将只在要处理的第一个链接中起作用。在第一个链接之后, Pelican将像 {filename} 一样处理 {attach}。这样可避免中断已处理的链接。

从多个文档链接到文件时要小心：由于 Pelican 没有定义处理文档的顺序，第一个指向文件的链接确定了其最终位置，因此在由多个文档链接的文件上使用 {attach}时会导致在不同的版本生成时文件位置发生更改（ cause its location to change from one site build to the next）。(这是否在实际中发生受操作系统、文件系统、Pelican 版本以及从项目中添加、修改或删除的文档的影响。）任何链接到文件旧位置的外部站点都可能会发现它们的链接已失效。因此, 仅当在链接的文档在同一个目录下时，才建议使{attach}，并且要同时全部使用{attach}。It is therefore advisable to use {attach} only if you use it in all links to a file, and only if the linking documents share a single directory. 在这样的情况下, 文件的输出位置在将来的生成中不会更改。在无法采取这些预防措施的情况下, 请考虑使用 {filename} 链接而不是 {attach} , 并让该文件的位置由项目的 STATIC_SAVE_AS 和 STATIC_URL 设置确定。(每个文件 save_as 和 url 仍然可以在 EXTRA_PATH_METADATA 中设置重写。) 此段落翻译不好，大家将就看下

Linking to authors, categories, index and tags

你可以使用{author}name连接到作者；{category}foobar连接到类别；{index}到索引；{tag}tagname到标签。

Deprecated internal link syntax 快要过时的内部链接语法

为了与早期版本保持兼容, Pelican 仍然支持垂直条 (| |)的内部链接。例如: | filename | an_article.rst， | tag | tagname |， |category | foobar。语法从 | |到 {} 的改变是为了避免与扩展 Markdown 或 reST 的指令冲突。可能最终会删除对旧语法的支持。

Importing an existing site 从已存在的站点导入

可以用一个简单的脚本实现从 WordPress、Tumblr、Dotclear 和Rss feeds的导入，详见站点导入

Translations 翻译

提供多语种的文章是可行的，为了做到这些，你需要在文章或是页面中添加lang信息，并设置DEFAULT_LANG属性（默认英语[en])。有了这些设置, 将只列出具有默认语言的文章, 并且每篇文章都附有该文章的可用翻译列表。

Note：
Pelican 的核心功能不创建每个语言的翻译模板的子站点 (例如 example.com/de)。对于这样的高级功能, 可以使用 i18n_subsites 插件。

Pelican 使用文章的 URL “slug” 来确定两个或更多的文章是否是互相的翻译。可以在文件的信息(metadata)中手动设置slug;如果没有明确设置, Pelican 将通过标题自动生成slug。

下面给个例子，这里有两篇文章，一个英语一个法语。

英语文章：

Foobar is not dead
##################

:slug: foobar-is-not-dead
:lang: en

That's true, foobar is still alive!

法语版：

Foobar n'est pas mort !
#######################

:slug: foobar-is-not-dead
:lang: fr

Oui oui, foobar est toujours vivant !

发布内容后, 您可以看到这两篇文章中唯一的共同点就是slug, 它在这里是一个标识符。如果您不希望以这种方式显式定义该slug, 则必须确保翻译的文章标题相同, 因为将从文章标题自动生成slug。

如果不希望 DEFAULT_LANG 检测到某个特定文章的原始版本, 请在信息（metadata）中使用translation指定哪些帖子是翻译的版本：

Foobar is not dead
##################

:slug: foobar-is-not-dead
:lang: en
:translation: true

That's true, foobar is still alive!

Syntax highlighting 语法高亮

Pelican 可以为您的代码块提供彩色的语法高亮。为此, 您必须在内容文件中使用以下约定。

对于 reStructuredText, 请使用code-block指定要突出显示的代码类型 (在此示例中, 我们将使用 python)：

.. code-block:: python

   print("Pelican is a static site generator.")

对于使用 CodeHilite 扩展来提供语法高亮的Markdown, 请在代码块的正上方包含语言标识符, 同时缩进标识符和代码：

There are two ways to specify the identifier:

    :::python
    print("The triple-colon syntax will *not* show line numbers.")

To display line numbers, use a path-less shebang instead of colons:

    #!python
    print("The path-less shebang syntax *will* show line numbers.")

指定的语言标识符 (如 python、ruby) 应该出现在list of available lexers中。

使用 reStructuredText 时, 代码块指令 (code-block directive) 中提供了以下选项:

选项	有效值	描述
anchorlinenos	N/A	如果在`<a>`标记中显示行号
classprefix	String	标记类名
hl_lines	numbers	要突出显示的行的list, 其中要突出显示的行号由空格分隔。这类似于在Sphinx中的`emphasize-lines`, 但它不支持用连字符分隔的行号范围, 或逗号分隔的行号。
lineanchors	string	在lineanchors和-linenumber之间对其中的每一行进行包装。
………太多了了	去看原文吧	http://docs.getpelican.com/en/stable/content.html#syntax-highlighting

Note：不同的版本中, 您的 Pygments 模块可能没有所有可用的选项。有关每个选项的详细信息, 请参阅 Pygments 文档的 HtmlFormatter 部分。

例如, 下面的代码块启用行号, 从153开始, 并使用 pgcss 前缀 Pygments css 类, 以使名称更加独特, 并避免可能的 css 冲突:

.. code-block:: identifier
    :classprefix: pgcss
    :linenos: table
    :linenostart: 153

   <indented code block goes here>

Publishing drafts 草稿

如果要将文章发布为草稿 (例如, 在发布前供好友审阅)，可以将Status:draft 属性添加到其信息（metadata) 中。然后, 该文章将输出到 draft 文件夹, 而不在索引页上或任何类别或标记页上列出。

如果您想要所有文章自动作为草稿发布 (在文章完成前不会意外地发布), 请在 DEFAULT_METADATA 中包括以下状态:

DEFAULT_METADATA = {
    'status': 'draft',
}

若要在以上情况，即设置了默认状态为 “草稿” 时发布帖子, 请更新帖子的信息以包括Status: published。

学习小结

由于对rst格式并不熟悉，重点还是看了看怎么使用目录结构以及markdown。
文章中应该包括的信息有：

标记	内容
Title	标题
Date	yyyy-mm-dd hh:mm
Modified	修改时间，格式同上
Tags	标签
Slug	Slug用来指定文件名
Authors / Author	作者，作者
Summary	概要

链接是个重要的东西，会影响build以后的目录结构。让我欣喜的是居然还能够提供附件，这个比我预期要好很多。
多篇文章指向同一个文件那里没有看懂怎么回事，只能待将来实操多实验几次来总结了。

Justin-x

关注

1
点赞
踩
0

收藏

觉得还不错? 一键收藏
1
评论
复制链接

分享到 QQ

分享到新浪微博

扫一扫

专栏目录