创作主题

为了生成HTML输出,Pelican使用 Jinja 模板引擎由于其灵活性和简单的语法。如果你想创造自己的主题,请随时从 "simple" theme .

要使用已创建(或手动下载然后修改)的主题生成站点,可以通过 -t 旗帜:

pelican content -s pelicanconf.py -t /projects/your-site/themes/your-theme

如果您不想在每次调用中指定主题,可以定义 THEME 在您的设置中指向您首选主题的位置。

结构

要制作自己的主题,必须遵循以下结构:

├── static
│   ├── css
│   └── images
└── templates
    ├── archives.html         // to display archives
    ├── period_archives.html  // to display time-period archives
    ├── article.html          // processed for each article
    ├── author.html           // processed for each author
    ├── authors.html          // must list all the authors
    ├── categories.html       // must list all the categories
    ├── category.html         // processed for each category
    ├── index.html            // the index (list all the articles)
    ├── page.html             // processed for each page
    ├── tag.html              // processed for each tag
    └── tags.html             // must list all the tags. Can be a tag cloud.
  • static 包含将复制到输出的所有静态资源 theme 文件夹。上面的文件系统布局包括CSS和image文件夹,但这些只是示例。把你需要的放在这里。

  • templates 包含将用于生成内容的所有模板。上面列出的模板文件是必需的;如果有助于您在创建主题时保持有序,您可以添加自己的模板。

模板和变量

这个想法是使用一个简单的语法,可以嵌入到HTML页面中。本文档描述主题中应该存在哪些模板,以及在生成时将哪些变量传递给每个模板。

所有模板都将接收设置文件中定义的变量,只要它们都是大写字母。您可以直接访问它们。

公共变量

所有这些设置将对所有模板可用。

变量

描述

output_file

当前正在生成的文件的名称。例如,当Pelican呈现主页时,输出_文件将是“索引.html".

文章

The list of articles, ordered descending by date. All the elements are Article objects, so you can access their attributes (e.g. title, summary, author etc.). Sometimes this is shadowed (for instance, in the tags page). You will then find info about it in the all_articles variable.

日期

相同的文章列表,但按日期升序排列。

草稿

条款草案一览表

作者

(author,articles)元组的列表,包含所有作者和相应的文章(值)

类别

(category,articles)元组的列表,包含所有类别和相应的项目(值)

标签

(tag,articles)元组的列表,包含所有标记和相应的项目(值)

页面列表

hidden_pages

隐藏页的列表

draft_pages

草稿页列表

分选

URL包装器(目前是类别、标记和作者)有比较方法,可以方便地按名称排序:

{% for tag, articles in tags|sort %}

如果你想根据不同的标准排序, `Jinja's sort command`_ _有很多选择。

日期格式

Pelican根据您的设置和区域设置设置日期格式 (DATE_FORMATS / DEFAULT_DATE_FORMAT) and provides a locale_date attribute. On the other hand, the date attribute will be a datetime 对象。如果您需要自定义不同于设置的日期格式,请使用Jinja过滤器 strftime 那是Pelican的。用法与Python相同 strftime 格式化,但过滤器将执行正确的操作,并根据设置中给定的区域设置设置日期格式:

{{ article.date|strftime('%d %B %Y') }}

index.html

这是您博客的主页或索引,生成于 index.html .

如果分页处于活动状态,则后续页面将驻留在 index{{number}}.html .

变量

描述

articles_paginator

物品列表的paginator对象

articles_page

文章的当前页

articles_previous_page

上一页文章 (None 如果页面不存在)

articles_next_page

文章的下一页 (None 如果页面不存在)

dates_paginator

文章列表的paginator对象,按日期排序,升序。

dates_page

文章的当前页,按日期排序,升序。

dates_previous_page

上一页文章,按日期排序,升序 (None 如果页面不存在)

dates_next_page

文章的下一页,按日期排序,升序 (None 如果页面不存在)

page_name

“index”--用于分页链接

author.html

将为每个现有作者处理此模板,并根据 AUTHOR_SAVE_AS 设置 (Default: author/{{slug}}.html ). 如果分页处于活动状态,则默认情况下后续页面将驻留在 author/{{slug}}{{number}}.html .

变量

描述

作者

正在处理的作者的姓名

文章

作者的文章

日期

文章作者,但按日期排序,升序

articles_paginator

物品列表的paginator对象

articles_page

文章的当前页

articles_previous_page

上一页文章 (None 如果页面不存在)

articles_next_page

文章的下一页 (None 如果页面不存在)

dates_paginator

文章列表的paginator对象,按日期排序,升序。

dates_page

文章的当前页,按日期排序,升序。

dates_previous_page

上一页文章,按日期排序,升序 (None 如果页面不存在)

dates_next_page

文章的下一页,按日期排序,升序 (None 如果页面不存在)

page_name

作者网址后的一切 {{slug}} 已删除--对于分页链接很有用

category.html

将为每个现有类别处理此模板,并根据 CATEGORY_SAVE_AS 设置 (Default: category/{{slug}}.html ). 如果分页处于活动状态,则默认情况下后续页面将驻留在 category/{{slug}}{{number}}.html .

变量

描述

类别

正在处理的类别的名称

文章

此类别的文章

日期

此类别的文章,但按日期排序,升序

articles_paginator

物品列表的paginator对象

articles_page

文章的当前页

articles_previous_page

上一页文章 (None 如果页面不存在)

articles_next_page

文章的下一页 (None 如果页面不存在)

dates_paginator

文章列表的paginator对象,按日期排序,升序

dates_page

文章的当前页,按日期排序,升序

dates_previous_page

上一页文章,按日期排序,升序 (None 如果页面不存在)

dates_next_page

文章的下一页,按日期排序,升序 (None 如果页面不存在)

page_name

类别URL {{slug}} 已删除--对于分页链接很有用

article.html

每个文章都将处理此模板,并根据 ARTICLE_SAVE_AS 设置 (Default: {{slug}}.html ). 渲染时可以使用以下变量。

变量

描述

文章

要显示的项目对象

类别

当前项目的类别名称

放在项目源文件头中的任何元数据都将作为 article 对象。字段名将与元数据字段的名称相同,但所有小写字符除外。

例如,可以添加一个名为 FacebookImage 到项目元数据,如下所示:

Title: I love Python more than music
Date: 2013-11-06 10:06
Tags: personal, python
Category: Tech
Slug: python-je-l-aime-a-mourir
Author: Francis Cabrel
FacebookImage: http://franciscabrel.com/images/pythonlove.png

此新元数据将作为 article.facebookimage 在你 article.html 模板。例如,这将允许您为Facebook open graph标记指定一个图像,该图像将随每篇文章而更改:

<meta property="og:image" content="{{ article.facebookimage }}"/>

page.html

将为每个页面处理此模板,并根据 PAGE_SAVE_AS 设置 (Default: pages/{{slug}}.html ). 渲染时可以使用以下变量。

变量

描述

第页

要显示的页面对象。您可以访问它的标题、slug和内容。

tag.html

将为每个标记处理此模板,并根据 TAG_SAVE_AS 设置 (Default: tag/{{slug}}.html ). 如果分页处于活动状态,则默认情况下后续页面将驻留在 tag/{{slug}}{{number}}.html .

变量

描述

标签

正在处理的标记的名称

文章

与此标签相关的文章

日期

与此标记相关的文章,但按日期排序,升序

articles_paginator

物品列表的paginator对象

articles_page

文章的当前页

articles_previous_page

上一页文章 (None 如果页面不存在)

articles_next_page

文章的下一页 (None 如果页面不存在)

dates_paginator

文章列表的paginator对象,按日期排序,升序

dates_page

文章的当前页,按日期排序,升序

dates_previous_page

上一页文章,按日期排序,升序 (None 如果页面不存在)

dates_next_page

文章的下一页,按日期排序,升序 (None 如果页面不存在)

page_name

标记URL后的所有内容 {{slug}} 已删除--对于分页链接很有用

period_archives.html

此模板将为您每年的帖子处理,如果 YEAR_ARCHIVE_SAVE_AS 定义,每个月如果 MONTH_ARCHIVE_SAVE_AS 定义,并且每天如果 DAY_ARCHIVE_SAVE_AS 定义。

变量

描述

时期

形式的元组 (yearmonthday )指示当前时间段。 yearday 是数字,而 month 是一个字符串。此元组仅包含 year 如果时间段是一个给定的年份。它包含两个 yearmonth 如果时间段超过年和月等等。

您可以看到如何使用 period in the "simple" theme period_archives.html template .

物体

详细说明模板中可用和有用的对象属性。并非所有属性都列在这里,这是在模板中被认为有用的属性选择。

文章

项目的字符串表示是 source_path 属性。

属性

描述

作者

这个 Author 这篇文章的。

作者

列表 Authors 这篇文章的。

类别

这个 Category 这篇文章的。

内容

文章的呈现内容。

日期

表示项目日期的Datetime对象。

date_format

默认日期格式或区域设置日期格式。

default_template

默认模板名称。

in_default_lang

布尔值,表示文章是否用默认语言编写。

文章的语言。

locale_date

日期格式由 date_format .

元数据

项目标题元数据 dict .

save_as

保存文章页面的位置。

slug

页面段塞。

source_path

项目源文件的完整系统路径。

relative_source_path

相对路径自 PATH 到文章源文件。

地位

文章状态,可以是“已发布”或“草稿”中的任何一个。

总结

呈现的内容摘要。

标签

名单 Tag 物体。

模板

用于渲染的模板名称。

标题

文章标题。

翻译

翻译列表 Article 物体。

网址

文章页面的URL。

作者/类别/标签

这些对象的字符串表示是 name 属性。

属性

描述

名称

此对象的名称 1.

page_name

作者页面名称。

save_as

保存作者页的位置。

slug

页面段塞。

网址

指向作者页面的URL。

1

对于作者对象,来自 :authors:AUTHOR .

页面的字符串表示是 source_path 属性。

属性

描述

作者

这个 Author 本页的。

内容

页面的呈现内容。

日期

表示页面日期的Datetime对象。

date_format

默认日期格式或区域设置日期格式。

default_template

默认模板名称。

in_default_lang

布尔值,表示文章是否用默认语言编写。

文章的语言。

locale_date

日期格式由 date_format .

元数据

页眉元数据 dict .

save_as

保存页面的位置。

slug

页面段塞。

source_path

页面源文件的完整系统路径。

relative_source_path

相对路径自 PATH 到页面源文件。

地位

页面状态,可以是“已发布”、“隐藏”或“草稿”中的任何一个。

总结

呈现的内容摘要。

标签

名单 Tag 物体。

模板

用于渲染的模板名称。

标题

页面的标题。

翻译

翻译列表 Article 物体。

网址

页面的URL。

喂养

feed变量在3.0中发生了变化。现在每个变量都显式地在名称中列出ATOM或RSS。ATOM仍然是默认值。旧的主题需要更新。以下是提要变量的完整列表:

FEED_ATOM
FEED_RSS
FEED_ALL_ATOM
FEED_ALL_RSS
CATEGORY_FEED_ATOM
CATEGORY_FEED_RSS
AUTHOR_FEED_ATOM
AUTHOR_FEED_RSS
TAG_FEED_ATOM
TAG_FEED_RSS
TRANSLATION_FEED_ATOM
TRANSLATION_FEED_RSS

遗传

从3.0版开始,Pelican支持从 simple 主题,以便可以重用 simple 主题模板在您自己的主题。

如果 templates/ 主题的目录丢失,它将被来自 simple 主题。所以如果在 simple 主题适合你,你不必从头开始写一个新的模板。

也可以从中扩展模板 simple 在自己的主题中使用 {{% extends %}} 指令如下例所示:

{% extends "!simple/index.html" %}   <!-- extends the ``index.html`` template from the ``simple`` theme -->

{% extends "index.html" %}   <!-- "regular" extending -->

例子

有了这个系统,就可以用两个文件创建一个主题。

base.html

第一个文件是 templates/base.html 模板:

{% extends "!simple/base.html" %}

{% block head %}
{{ super() }}
   <link rel="stylesheet" type="text/css" href="{{ SITEURL }}/theme/css/style.css" />
{% endblock %}
  1. 在第一行,我们扩展 base.html 模板来自 simple 主题,所以我们不必重写整个文件。

  2. 在第三行,我们打开 head 已在中定义的块 simple 主题。

  3. 在第四行,函数 super() 保留以前插入的内容 head 块。

  4. 在第五行,我们向页面附加一个样式表。

  5. 最后一行,我们关闭 head 块。

此文件将由所有其他模板扩展,因此样式表将从所有页面链接。

style.css

第二个文件是 static/css/style.css CSS样式表:

body {
    font-family : monospace ;
    font-size : 100% ;
    background-color : white ;
    color : #111 ;
    width : 80% ;
    min-width : 400px ;
    min-height : 200px ;
    padding : 1em ;
    margin : 5% 10% ;
    border : thin solid gray ;
    border-radius : 5px ;
    display : block ;
}

a:link    { color : blue ; text-decoration : none ;      }
a:hover   { color : blue ; text-decoration : underline ; }
a:visited { color : blue ;                               }

h1 a { color : inherit !important }
h2 a { color : inherit !important }
h3 a { color : inherit !important }
h4 a { color : inherit !important }
h5 a { color : inherit !important }
h6 a { color : inherit !important }

pre {
    margin : 2em 1em 2em 4em ;
}

#menu li {
    display : inline ;
}

#post-list {
    margin-bottom : 1em ;
    margin-top : 1em ;
}

下载

您可以下载这个示例主题 here .