写作内容¶
文章和页数¶
Pelican认为“文章”是按时间顺序排列的内容，例如博客上的帖子，因此与日期相关。
“页面”背后的想法是，它们通常不是临时性的，用于不经常更改的内容（例如，“关于”或“联系人”页面）。
您可以在存储库中的以下位置找到示例内容： samples/content/ .
文件元数据¶
Pelican试图足够聪明地从文件系统中获取所需的信息（例如，关于文章的类别），但是您需要在文件中以元数据的形式提供一些信息。
如果您正在以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
作者和标记列表可以用分号分隔，这样可以编写包含逗号的作者和标记：
:tags: pelican, publishing tool; pelican, bird
:authors: Metaireau, Alexis; Doyle, Conan
Pelican实现了一个扩展来重新构造文本，以支持 abbr HTML标记。要使用它，请在你的帖子中写下这样的话：
This will be turned into :abbr:`HTML (HyperText Markup Language)`.
也可以使用降价语法（文件以结尾 .md ， .markdown ， .mkd 或 .mdown ). 降价生成要求您首先显式安装 Python-Markdown 包，可以通过 pip install Markdown .
Pelican也支持 Markdown Extensions ，如果默认设置中未包含，则可能需要单独安装 Markdown 可以通过 MARKDOWN 设置。
降价公告的元数据语法应遵循以下模式：
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.
您还可以拥有自己的元数据键（只要它们不与保留的元数据关键字冲突）用于模板中。下表包含保留的元数据关键字列表：
元数据 |
描述 |
|---|---|
|
文章或页的标题 |
|
出版日期（例如。， |
|
修改日期（例如。， |
|
内容标记，用逗号分隔 |
|
内容关键字，用逗号分隔（仅限HTML内容） |
|
内容类别（仅一个-不是多个） |
|
URL和翻译中使用的标识符 |
|
内容作者，当只有一个时 |
|
当有多个 |
|
索引页内容简述 |
|
内容语言ID ( |
|
如果内容是另一个的翻译 ( |
|
内容状态： |
|
用于生成内容的模板的名称（不带扩展名） |
|
将内容保存到此相对文件路径 |
|
用于此文章/页面的URL |
其他格式的读取器（例如 AsciiDoc) 可通过插件获得。参考 pelican-plugins 存储库。
Pelican还可以处理以结尾的HTML文件 .html 和 .htm . Pelican以非常直接的方式解释HTML，从中读取元数据 meta 标签，标题来自 title 把尸体从 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中的标准，或通过 keywords 元数据，在HTML中是标准的。两者可以互换使用。
请注意，除了标题之外，这些内容元数据都不是必需的：如果未指定日期 DEFAULT_DATE 设置为 'fs' ，Pelican将依赖文件的“mtime”时间戳，并且类别可以由文件所在的目录确定。例如，位于 python/foobar/myfoobar.rst 将有一个类别 foobar . 如果要以其他方式组织文件，而子文件夹的名称不是好的类别名称，则可以设置该设置 USE_FOLDER_AS_CATEGORY 到 False . 当解析页面元数据中给定的日期时，Pelican支持W3C `suggested subset ISO 8601`_ _.
所以标题是唯一需要的元数据。如果这让你烦恼，不用担心。您可以使用源内容文件名作为标题，而不是每次在元数据中手动指定标题。例如，一个名为 Publishing via Pelican.md 会自动分配一个标题 通过Pelican出版 . 如果您喜欢这种行为，请将以下行添加到设置文件中：
FILENAME_METADATA = '(?P<title>.*)'
注解
当尝试使用不同的设置（尤其是元数据设置）时，缓存可能会干扰，并且更改可能不可见。在这种情况下，使用禁用缓存 LOAD_CONTENT_CACHE = False 或者使用 --ignore-cache 命令行开关。
modified 应该是您上次更新文章的时间，并且默认为 date 如果未指定。而且你可以展示 modified 在模板中，当您设置 modified 修改文章后的当前日期。
authors 是以逗号分隔的文章作者列表。如果只有一个作者你可以使用 author 字段。
如果未显式指定给定帖子的摘要元数据，则 SUMMARY_MAX_LENGTH 设置可用于指定从文章开头开始有多少单词用作摘要。
也可以通过要在中设置的正则表达式从文件名中提取任何元数据 FILENAME_METADATA 设置。所有匹配的命名组都将在元数据对象中设置。的默认值 FILENAME_METADATA 设置将只从文件名中提取日期。例如，如果要同时提取日期和slug，可以设置如下内容： '(?P<date>\d{{4}}-\d{{2}}-\d{{2}})_(?P<slug>.*)'
请注意，文件中可用的元数据优先于从文件名中提取的元数据。
页¶
如果您创建一个名为 pages 在content文件夹中，其中的所有文件都将用于生成静态页面，例如 关于 或 联系 页。（请参阅下面的文件系统布局示例。）
你可以使用 DISPLAY_PAGES_ON_MENU 设置以控制是否在主导航菜单中显示所有这些页面。（默认为 True ）
如果要排除链接到菜单或在菜单中列出的任何页面，请添加 status: hidden 属性设置为其元数据。这对于制作符合站点生成主题的错误页面之类的事情非常有用。
静态含量¶
静态文件是指除文章和页面之外的文件，它们按原样复制到输出文件夹中，而不进行处理。您可以使用控制复制哪些静态文件 STATIC_PATHS 项目的设置 pelicanconf.py 文件。Pelican的默认配置包括 images 目录，但其他目录必须手动添加。此外，还包括显式链接到的静态文件（见下文）。
同一目录中的混合内容¶
从pelican3.5开始，静态文件可以安全地与页面源文件共享一个源目录，而无需在生成的站点中公开页面源。任何此类目录都必须添加到这两个目录中 STATIC_PATHS 和 PAGE_PATHS （或） STATIC_PATHS 和 ARTICLE_PATHS ). Pelican将正常识别和处理页面源文件，并复制其余文件，就像它们位于为静态文件保留的单独目录中一样。
注意：将静态源文件和内容源文件放在同一个源目录中并不保证它们最终会在生成的站点中的同一个位置。最简单的方法是使用 {{attach}} 链接语法（如下所述）。或者 STATIC_SAVE_AS ， PAGE_SAVE_AS 和 ARTICLE_SAVE_AS 设置（以及相应的 *_URL 设置）可以配置为将不同类型的文件放在一起，就像在早期版本的Pelican中一样。
链接到内部内容¶
从Pelican 3.1开始，现在可以指定指向 源内容 中的层次结构而不是文件 生成 等级制度。这使得从当前帖子链接到可能位于该帖子旁边的其他内容变得更加容易（而不必在站点生成后确定其他内容将放置在何处）。
链接到内部内容（文件 content directory), use the following syntax for the link target: {{filename}}path/to/file Note: forward slashes, /, are the required path separator in the `` {filename}``指令，适用于所有操作系统，包括Windows。
例如，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)
链接到静态文件¶
可以使用链接到静态内容 {{static}}path/to/file . 使用此语法链接到的文件将自动复制到输出目录，即使包含这些文件的源目录不包含在 STATIC_PATHS 项目的设置 pelicanconf.py 文件。
例如，项目的内容目录的结构可能如下所示：
content
├── images
│ └── han.jpg
├── pdfs
│ └── menu.pdf
└── pages
└── test.md
test.md 包括：
[Our Menu]({static}/pdfs/menu.pdf)
然后站点生成将复制 han.jpg 到 output/images/han.jpg ， menu.pdf 到 output/pdfs/menu.pdf ，并在 test.md .
如果你使用 {{static}} 为了链接到一篇文章或一个页面，这将变成一个链接到它的源代码。
附加静态文件¶
从Pelican 3.5开始，可以使用以下链接目标语法将静态文件“附加”到页面或文章： {{attach}}path/to/file 这就像 {{static}} 语法，但也会将静态文件重新定位到链接文档的输出目录中。如果静态文件来自链接文档源下的子目录，则输出时将保留该关系。否则，它将成为链接文档的同级。
这只适用于链接到静态文件。
例如，项目的内容目录的结构可能如下所示：
content
├── blog
│ ├── icons
│ │ └── icon.png
│ ├── photo.jpg
│ └── testpost.md
└── downloads
└── archive.zip
pelicanconf.py 包括：
PATH = 'content'
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
[Downloadable File]({attach}/downloads/archive.zip)
站点生成将生成一个如下结构的输出目录：
output
└── 2014
├── archive.zip
├── icons
│ └── icon.png
├── photo.jpg
└── test-post.html
请注意，使用 {{attach}} 在文章的输出目录中或下面结束。
如果静态文件被多次链接，则 {{attach}} 只会在第一个链接中工作。在第一个环节后，Pelican将治疗 {{attach}} 喜欢 {{static}} . 这样可以避免断开已处理的链接。
从多个文档链接到文件时要小心： 由于文件的第一个链接确定了文件的位置，而Pelican没有定义文档的处理顺序，使用 {{attach}} 在由多个文档链接的文件上，可能会导致其位置从一个网站生成更改为下一个网站生成。（在实践中是否会发生这种情况将取决于操作系统、文件系统、Pelican版本以及从项目中添加、修改或删除的文档。）任何链接到文件旧位置的外部站点可能会发现它们的链接断开。 因此，建议只在指向文件的所有链接中使用{{attach}}，并且仅当链接文档共享一个目录时才使用它。 在这些情况下，文件的输出位置在将来的构建中不会更改。在这些预防措施不可行的情况下，考虑使用 {{static}} 而不是链接 {{attach}} ，并让文件的位置由项目的 STATIC_SAVE_AS 和 STATIC_URL 设置。（每个文件 save_as 和 url 仍然可以在中设置覆盖 EXTRA_PATH_METADATA ）
注解
使用时 {{attach}} ，中的任何父目录 *_URL / *_SAVE_AS 设置应该相互匹配。另请参见： URL设置
不推荐使用的内部链接语法¶
为了保持与早期版本的兼容，Pelican仍然支持垂直条 (|| )除了大括号 ({{}} )对于内部链接。例如： |filename|an_article.rst ， |tag|tagname ， |category|foobar . 语法已从更改 || 到 {{}} 以避免与Markdown扩展或reST指令冲突。同样，与Pelican链接内容也支持 {{filename}} . 语法已更改为 {{static}} 允许链接到生成的文章和页面及其静态源。
对旧语法的支持最终可能会被删除。
包括其他文件¶
Markdown和restructedText语法都提供了这种机制。
下面是一些 重构文本 使用 the include directive ：
.. include:: file.rst
包括由两个标识符分隔的文件片段，突出显示为C++（基于行数的切片也是可能的）：
.. include:: main.cpp :code: c++ :start-after: // begin :end-before: // end
包括一个原始HTML文件（或一个内联SVG）并将其直接放入输出而不进行任何处理：
.. raw:: html :file: table.html
为了 Markdown ，必须依赖扩展。例如，使用 mdx_include plugin ：
```html {! template.html !} ```
导入现有站点¶
可以使用一个简单的脚本从WordPress、Tumblr、Dotclear和RSS提要导入站点。看到了吗 导入现有站点 .
翻译¶
翻译文章是可能的。为此，您需要添加一个 lang 你的文章/页面的meta属性，并设置一个 DEFAULT_LANG 设置（英语 [en] 默认情况下）。有了这些设置，将只列出具有默认语言的文章，并且每篇文章都会附带该文章的可用翻译列表。
注解
Pelican的核心功能不创建子站点（例如。 example.com/de )每种语言的翻译模板。对于这种高级功能 i18n_subsites plugin 可以使用。
默认情况下，Pelican使用文章的URL“slug”来确定两篇或多篇文章是彼此的翻译。（这可以用 ARTICLE_TRANSLATION_ID 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 !
尽管有Post-content-quality，但是您可以看到这两篇文章之间唯一的共同点是slug，它在这里起标识符的作用。如果你要明确地定义这篇文章的标题是自动生成的，那么你必须确保这篇文章的标题是完全相同的。
如果不希望某个特定项目的原始版本被 DEFAULT_LANG 设置，使用 translation 用于指定哪些文章是翻译的元数据：
Foobar is not dead
##################
:slug: foobar-is-not-dead
:lang: en
:translation: true
That's true, foobar is still alive!
语法突出显示¶
Pelican可以为代码块提供彩色语法高亮显示。为此，必须在内容文件中使用以下约定。
对于reStructuredText，请使用 code-block 指令指定要突出显示的代码类型（在这些示例中，我们将使用 python ）：
.. code-block:: python
print("Pelican is a static site generator.")
对于降价，它利用 CodeHilite extension 要提供语法高亮显示，请在代码块上方包含语言标识符，同时缩进标识符和代码：
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 .
使用RestructedText时，代码块指令中提供以下选项：
期权 |
有效值 |
描述 |
|---|---|---|
锚链 |
不适用 |
如果存在，将行号换行到<a>标记中。 |
类前缀 |
一串 |
在令牌类名前面加上字符串 |
hl_lines |
数字 |
要高亮显示的行的列表，其中要高亮显示的行号用空格分隔。这与 |
线针 |
一串 |
使用这个字符串和-linenumber将每一行包装在锚中。 |
线路编号 |
一串 |
如果存在或设置为“table”则输出表中的行号，如果设置为“inline”，则以inline方式输出“无”表示不输出此表的行号。 |
线路特殊 |
数 |
如果设置，则每n行将被赋予“特殊”css类。 |
线条艺术 |
数 |
第一行的行号。 |
线谱 |
数 |
打印第n行号。 |
行分隔符 |
一串 |
要在代码行之间打印的字符串，默认为“n”。 |
线跨 |
一串 |
用这个和-linenumber将每一行换行。 |
没有背景 |
不适用 |
如果设置，则不输出包装元素的背景色 |
诺拉普 |
不适用 |
如果设置，则根本不包装标记。 |
标签文件 |
一串 |
用于名称定义的ctags文件。 |
标签格式 |
一串 |
ctag链接的格式。 |
请注意，根据版本的不同，Pygments模块可能没有所有这些选项可用。请参阅 HtmlFormatter 剖面图 Pygments documentation 有关每个选项的详细信息。
例如，下面的代码块启用行号，从153开始，并在Pygments CSS类前面加上 pgcss公司 要使名称更具唯一性并避免可能的CSS冲突：
.. code-block:: identifier
:classprefix: pgcss
:linenos: table
:linenostart: 153
<indented code block goes here>
也可以指定 PYGMENTS_RST_OPTIONS 变量，以包含将自动应用于每个代码块的选项。
例如，如果要为每个代码块和CSS前缀显示行号，则可以将此变量设置为：
PYGMENTS_RST_OPTIONS = {'classprefix': 'pgcss', 'linenos': 'table'}
如果指定，各个代码块的设置将覆盖设置文件中的默认值。
发布草稿¶
如果要将文章或页面发布为草稿（例如，供朋友在发布前审阅），可以添加 Status: draft 属性设置为其元数据。然后将该文章输出到 drafts 文件夹，不在索引页或任何类别或标记页上列出。
如果您的文章应自动作为草稿发布（以避免在文章完成之前意外发布），请将状态包含在 DEFAULT_METADATA ：
DEFAULT_METADATA = {
'status': 'draft',
}
在默认状态为时发布文章 draft ，更新帖子的元数据以包括 Status: published .