布局模板 - 自定义 HTML 布局

2021-11-16

布局模板基础使用方法

可以使用主题自带的模板，比如错误页面，可以直接使用404.html， 只需要在metadata中添加layout键值即可

---
layout: 404.html
---

自定义布局模板

首先写布局模板文件, 支持 Jinja2 语法, 写法可以参考默认主题插件的布局模板的写法.

模板文件可以放到两个地方, 一个是放到主题插件里面, 插件作者可以这样做；

另一个就是放到布局模板文件夹(默认文档根目录layout)下, 然后单独对特定的页面使用特定的布局模板, 在文章头部metadata处添加layout键值:
layout: 页面使用的布局模板, 默认不需要这个键值, 会使用主题插件里面的配置,需要你需要自定义这个页面的布局, 可以设置这个参数, 路径相对于site_config中的layout_root_dir路径, layout_root_dir 默认为layout, 所以要使用layout/special_layout.html 只需要填写special_layout.html

可以基于主题的模板修改，或者继承主题的模板，比如小改一下404.html页面的body部分，只需在layout目录下新建一个my_404.html， 注意文件名不能和内置的文件名冲突， 如果冲突会提示generate html fail: maximum recursion depth exceeded in comparison:

{% extends "404.html" %}

{% block body_404 %}

这里是 body
{{ body|safe }}

{% endblock%}

然后在404.md中使用这个模板

---
layout: my_404.html
---

jinja2 模板变量

这里列出了所有的支持的变量:

page head info

  • lang: language, e.g. en, or zh-CN
  • metadata: metadata from doc metadata, dict type
  • page_id: page id , a string, set in doc config and doc metadata
  • page_classes: page classes, a list, set in doc config and doc metadata
  • keywords: keywords, a list, set in doc metadata
  • description: description, a string, set in doc metadata
  • header_items: tags in head(<head></head>) tag, a string list
  • title: page title, can be null, string, set in doc metadata
  • site_name: site name, string, set in site config
  • js_vars: js variables set and used by plugins, a dict object
  • logo_url: site logo image url, string, can be null, set in doc config
  • logo_alt: site logo alt info, string, can be null, set in doc config
  • home_url: home url, e.g. "/", "/site0/", string
  • navbar_title: navbar title, html string, can be null, set in doc config
  • navbar_main: navbar left html, html string
  • navbar_options: navbar right html, html string
  • navbar_plugins: navbar plugins html, html string

pages no sidebar, only article of docs have

  • sidebar_title: sidebar title, string, can be html string, set in doc sidebar config
  • sidebar_items_html: sidebar items html, html string

body info

article of docs body info

  • article_title: doc's article title, string, set in doc metadata
  • tags: article tags, a string list, set in doc metadata
  • author: article author, string, can be null, set in doc metadata
  • date: article create date, string, can be null, set in doc metadata
  • show_source: show source button info, string, can be null, set in site config and doc metadata
  • source_url: source file's url, valid only when show_source is not null
  • body: body html, html string
  • previous: previous article, can be null
    • title: previous article title, string
    • url: previous article url, string
  • next: next article
    • title: next article title, string
    • url: next article url, string
  • toc: toc html string, can be null

pages body info

  • body: body html, html string

page footer info

  • footer_top: footer top html string
  • footer_bottom: footer bottom html string
  • footer_js_items: js items last load int html, string list