主题命名

主题以文件夹的形式存于 _themes 文件夹内，主题的名字就是文件夹名，不要使用中文和奇怪的符号命名。

制作建议

主题名字以英文字母开头，仅使用小写字母、数字 - 和 _（不使用空格 space）。
如果你要将主题发布到 Github 上，项目名建议命名为 beex-theme-xxx 的形式以便用户搜索。
没有分页，请参考 Beex 的设计哲学关于翻页的部分。
模板引擎是 Tera，但中文资料很少，所以制作主题可以先参考 Jinja2 的文档，基本概念就是 {% if %} {% for %} {% block %} {% extends %} {{ filter }} {% macro %} 这几个，使用高级用法前核对 Tera 的文档是否支持。
存放 .css .js 等文件的文件夹，以 static 命名。
注意

模板默认 escape 全部变量，所以 content 和 url 需要手动标记 safe，否则会被 escape 为 HTML entities。
```
{{ archive.content | safe }}
{{ archive.url | safe }}
```

制作主题

Beex 默认会生成 beex_simple 主题，我还提供本站使用的主题，以供参考。

主题文件

文件结构

主题以文件夹的形式存储在 _themes 目录中，在 _config.toml 文件中 theme 指定要使用的主题文件夹名。

大致结构为：

_themes
    +---my_theme
        +---static
        |   |---actions.js
        |   \---style.css
        +---templates
        |   |---bar.html
        |   \---foo.html
        |---archive.html
        |---archives.html
        \---index.html

一般而言，index.html（首页）、archive.html（文章页）、archives.html（列表页）三个模板文件就可以做出一个完整的主题。你还可以针对分类和标签制作专门的页面，以及制作 BeexMeta.template 指定的模板。

文件	作用	Rollback
index.html	首页	必须存在
archive.html	文章页	index.html
archives.html	文章列表页	index.html
categories.html	全部分类的列表	archives.html
category.html	每个分类的文章列表	archives.html
tags.html	全部分类的列表	archives.html
tag.html	每个标签的文章列表	archives.html
templates/*.html	文章页单独指定的自定义模板	archive.html

Rollback（中文：回退）的意思是当某个模板文件不存在时，寻找另一个模板文件代替。

建议

尽管不是强制的，但由于关闭评论也是常见的需求，所以如果你制作的主题 archive.html 中预留了评论标签的 {% block %}，建议同时自带一个 templates/no-comment.html 模板文件清空这个 block。

这样所有 Beex 用户对于不想添加评论的页面可以统一使用 BeexMeta.template: no-comment.html 这个设置。

静态文件

.css 和 .js 文件可能会被设置缓存，编辑后，老访客因为有缓存看不到新效果，所以我为模板增加了一个过滤器 to_static，自动为静态文件添加版本信息。使用方法如下：

<link rel="stylesheet" type="text/css"
    href="{{ 'static/style.css' | to_static | safe }}">

'static/style.css' 是一个字符串，必须用引号括起来，使用单引号和双引号均可。
static/style.css 以你的主题文件夹为父目录。以 beex_simple 为例，这个文件位于 _themes/beex_simple/static/style.css。不要使用 / 开头。
to_static 会输出文件的最终路径，并添加版本号。
因为这是一个链接，所以用 safe 标记，避免被 escape。
因为 Beex 是增量构建的，所以编辑模板文件后要使用 bx gen --force 重建整个站点。

主题变量

都是一些语义明确的单词。

站点信息

site
- 全部页面

{{ site.title }}
{{ site.tagline }}

0.5.0 新增

{{ site.author }}

菜单

0.2.0 新增

menus
- 全部页面

有两个菜单，menus.main 和 menus.top。~~没有内置支持类似 .is_active 的属性，请用 JavaScript 实现。~~可以通过ctx.current_url判断。

{% for menu_item in menus.main %}
    {{ menu_item.title }}
    {{ menu_item.url | safe }}
    {% for sub_item in menu_item.children %}
        {{ sub_item.title }}
        {{ sub_item.url | safe }}
    {% endfor %}
{% endfor %}

{% for menu_item in menus.top %}
    // 与 `menus.main` 相同，省略...
{% endfor %}

文章信息

archive
- 文章页（archive.html）

{{ archive.title }}
{{ archive.url | safe }}
{{ archive.categories }}  // category 的列表
{{ archive.tags }}  // tag 的列表
{{ archive.sticky }}
{{ archive.created }}
{{ archive.short }}
{{ archive.content | safe }}
{{ archive.summary | safe }}  // 内容摘要，0.5.0 新增
{{ archive.thumbnail | safe }}  // 缩略图地址，0.8.0 新增
{{ archive.previous.title }}  // 上一篇文章标题，0.8.1 新增
{{ archive.previous.url | safe }}  // 上一篇文章链接地址，0.8.1 新增
{{ archive.next.title }}  // 下一篇文章标题，0.8.1 新增
{{ archive.next.url | safe }}  // 下一篇文章链接地址，0.8.1 新增

{% for category in archive.categories %}
    {{ category.title }}
    {{ category.url | safe }}
{% endfor %}

{% for tag in archive.tags %}
    {{ tag.title }}
    {{ tag.url | safe }}
{% endfor %}

分类（标签）文章列表

categoies
- 全部分类列表页（categories.html）
- 分类文章列表页（category.html）
tags
- 全部标签列表页（tags.html）
- 标签文章列表页（tag.html）
提示

每个分类文章列表页也使用 categories 列表，只是这个列表里只有一个元素，这样设计是为了方便模板 rollback，标签页同理。
注意

列表页的文章信息，不包含 {{ archive.content }}。

{% for category in categories %}
    {{ category.title }}
    {{ category.url | safe }}
    {% for archive in category.archives %}
        {{ archive.title }}
        // 同上面“文章信息”，省略...
    {% endfor %}
{% endfor %}

{% for tag in tags %}
    // ...
{% endfor %}

文章列表

archives
- 全部文章列表页（archives.html）
- 首页（index.html）
注意

列表页的文章信息，不包含 {{ archive.content }}。

{% for archive in archives %}
    // 同“文章信息”，省略...
{% endfor %}

其他

ctx
- 全部页面

一些有用的上下文变量

{{ ctx.current_url }}：当前页面的 URL 路径，如果文件名为 index.html 或 index.htm 则不包含文件名。（0.6.0 新增）
已经废弃的
- ~~{{ ctx.current_url_path }}：当前页面的 URL 路径，如果文件名为 index.html 或 index.htm 则不包含文件名。~~（0.5.0 新增，0.6.0 废弃）

章节目录

有时可能希望为某些的页面显示一个列表，将多篇文章组织成一个系列。这可以通过自定义模板来实现，具体请参考：Beex 章节