• Github 中文镜像
Sign inSign up
Watch966
Star102.4k
Fork61.8k
Branch: working.beex.help
Switch branches/tags
Branches
Tags
  •  
K / Beex 主题模板(Templates).md
移动浏览 Clone
加载中...
到移动设备上浏览
227 lines 14.46 kB
First commit on 11 Jun 2020

    主题命名

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

    制作建议

    • 主题名字以英文字母开头,仅使用小写字母、数字 -_(不使用空格 space)。

    • 如果你要将主题发布到 Github 上,项目名建议命名为 beex-theme-xxx 的形式以便用户搜索。

    • 没有分页,请参考 Beex 的设计哲学关于翻页的部分。

    • 模板引擎是 Tera,但中文资料很少,所以制作主题可以先参考 Jinja2 的文档,基本概念就是 {% if %} {% for %} {% block %} {% extends %} {{ filter }} {% macro %} 这几个,使用高级用法前核对 Tera 的文档是否支持。

    • 存放 .css .js 等文件的文件夹,以 static 命名。

    • 注意

      模板默认 escape 全部变量,所以 contenturl 需要手动标记 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.mainmenus.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.htmlindex.htm 则不包含文件名。(0.6.0 新增

    • 已经废弃的

      • {{ ctx.current_url_path }}:当前页面的 URL 路径,如果文件名为 index.htmlindex.htm 则不包含文件名。0.5.0 新增,0.6.0 废弃

    章节目录

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