Pyon Pyon Today

[译]如何为pelican制作主题(无限修订中)

2013-07-12 Translation

好吧,要做主题,这才是真正开始。

翻译的时候好多地方都不知道怎么表达,望大神指点。

如何为 Pelican 制作主题

Pelican 使用著名的 Jinja2 模板引擎来生成它的 HTML 输出。Jinja2 的语法非常简单。如果你想要制作你自己的主题,随意看看 “simple”主题 或许能给你一些灵感。

主题的结构

制作主题时,你必须遵守下列结构

├──── static
│   ├── css
│   └── images
└──── templates
    ├── archives.html // 用来显示文章存档
    ├── period_archives.html  //用来显示根据时间段划分的文章存档
    ├── article.html  // 用来处理每篇文章的页面
    ├── author.html   // 用来处理各个作者的页面
    ├── authors.html  // 必须列出所有作者
    ├── categories.html   // 必须列出所有目录
    ├── category.html // 用来处理各个目录
    ├── index.html// Index页面,列出所有文章
    ├── page.html // 用来处理每个page
    ├── tag.html  // 用来处理每个标签
    └── tags.html // 必须列出所有标签,可以是标签云
  • static包含了所有的静态文件,最后会被复制到输出中的theme目录下。我把 CSS 和 image 目录放在了这里,不过这只是举例,把你需要的东西放在这里。
  • templates 包含了所有被用来生成页面的模板。我只在这里存放了必需的模板,你可以自己定义对你来说有用的模板。

模板与变量

我们的想法是使用可以嵌入进 HTML 的简单语法。这个文件描述了哪些模板存在于主题中,哪些变量将会在生成时被传递给每个模板。

所有的模板都会接收到你在设置文件中定义的全部大写的变量。你可以直接访问这些变量。

公共变量

这些设置对所有模板都有效。

变量描述
output_file正在生成的文件的名字。举个例子,Pelican渲染主页的时候,output_file将会是“index.html”.
articles文章列表,依日期降序排列所有类型为Aritcle对象的元素,你可以访问它们的属性(比如标题,概要,作者…)。有时会被屏蔽(例如在tags页面中)。你可以在变量all_articles 中找到关于它的信息。
dates同样是文章列表,不过是依日期升序排列。
tags一个包含数个(tag,articles)元组的列表。包含了所有的标签和使用特定标签的所有文章的列表构成的元组。
categories一个包含数个(category,articles)元组的列表。包含了所有分类和在特定分类下所有文章的列表构成的元组。
pagespages的列表

排序

URL wrappers (currently categories, tags, and authors), have comparison methods that allow them to be easily sorted by name:

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

如果你想依照其它标准进行排序, Jinja 的 sort 命令 拥有很多选项。

日期格式化

Pelican 依据你的设置和区域(DATE_FORMATS/DEFAULT_DATE_FORMAT)来提供一个locale_date属性。另一方面,date属性蒋成为一个datetime对象。如果你需要与当前设置不同的日期格式,使用 Pelican 自带的 Jinja 过滤器strftime,用法和 Python 中的 strftime 是一样的,过滤器会正确地根据你设置的区域正确地对日期进行格式化。

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

index.html

这是博客的主页,生成到 output/index.html 。

如果启用了分页,后续的页面会被保存在 output/index`n`.html 。

变量描述
articles_paginator一个用来处理文章列表的paginator对象
articles_page文章列表的当前页面
dates_paginator一个用来处理文章的paginator对象,依照日期升序进行排序
dates_page文章列表的当前页面,依照日期升序排列
page_name“索引” - 很有用的分页链接

author.html

这个模板将用来处理每个作者的页面,输出为 output/author/authorname_.html。

变量描述
author作者名
articles该作者的文章
dates该作者的文章,依日期升序排序
articles_paginator一个用于文章列表的paginator对象
articles_page文章的当前页
dates_paginator一个用于文章列表的paginator对象,依日期升序排序/td>
dates_page文章的当前页,依日期升序排序
page_nameAUTHOR_URL:在{slug}后面的一切都被去掉了 - 对分页链接很有用

category.html

这个模板会用来处理每个分类,输出为 output/category/categoryname_.html。

如果启用了分页,后续的页面将依照 CATEGORYSAVEAS(默认值: output/category/\category_name’n’.html)输出。

变量描述
category目录名
articles该目录的文章
dates该目录的文章,按日期升序排列
articles_paginator一个文章列表的paginator对象
articles_page文章的当前页
dates_paginator一个文章列表的paginator对象,按日期升序排列
dates_page文章当前页,按日期升序排列
page_nameCATEGORY\_URL:在{slug}后面的一切都被去掉了 - 对分页链接很有用

article.html

这个模板用来处理每篇文章,输出为 output/articlename_.html。这里是它特有的变量。

变量描述
article要被显示的article对象
category当前文章所属分类的名称

page.html

这个模板用来处理每个 page 页面,相应输出为 output/pagename_.html。

变量描述
page要显示的page对象,你可以访问它的标题,slug和内容

tag.html

这个模板用来处理各个标签,相应的输出为 output/tag/tagname_.html。

如果启用了分页,后续的页面将依照 TAGSAVEAS(默认值: output/tag/\tag_name’n’.html)输出。

变量描述
tag标签名
articles与该标签相关的文章
dates与该标签相关的文章,依照日期升序排序
articles_paginator一个文章列表的paginator对象
articles_page文章当前所在页
dates_paginator一个文章列表的paginator对象,依照日期升序排序
dates_page文章当前所在页,依照日期升序排序
page_nameTAG_URL:在{slug}后面的一切都被去掉了 - 对分页链接很有用

Feeds

feed 变量在 3.0 版本(译者注:指 Pelican,下同)中有所改变,现在每个变量在名字中显式列出是 ATOM 还是 RSS。ATOM 依然是默认的。旧主题可能因此需要更新。下面是所有的 feed 变量

  • FEED_ATOM
  • FEED_RSS
  • FEEDALLATOM
  • FEEDALLRSS
  • CATEGORYFEEDATOM
  • CATEGORYFEEDRSS
  • TAGFEEDATOM
  • TAGFEEDRSS
  • TRANSLATIONFEEDATOM
  • TRANSLATIONFEEDRSS

继承

自从 3.0 版本开始,Pelican 支持继承simlpe主题,你可以在你的主题里面重用simple主题中的模板。

如果你的templates/目录下的某个必需模板丢失了,它将被simple主题中的对应模板替代。因此,如果simple主题中的模板的 HTML 结构是适合你的,你就不需要从头写一个全新的模板。

你也可以在你的主题中对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. 在第一行,我们扩展了simple主题中的base.html,所以我们不需要重写整个文件。
  2. 第三行,我们开始了在 simple 主题中定义好的 head 块。
  3. 第四行,super() 函数保持先前插入的head 块不结束。
  4. 第五行,我们为页面添加了一个样式表。
  5. 最后一行,我们结束了head 块。

这个文件将被所有其它的模板(译者注:tags.html,articles.html…)扩展,所以样式表会被连接到所有页面中。

style.css

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

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 ;
}

下载

你可以从这里下载这个样例主题

源文档

原文链接:http://docs.getpelican.com/en/latest/themes.html