主题开发

lizheming edited this page Feb 26, 2017 · 3 revisions

Firekylin 支持主题切换功能,你完全可以自行开发一款自己喜欢的主题。下面就为大家讲解如何开发一款 Firekylin 主题。

文件结构

Firekylin 主题使用了 nunjucks 模板语法,可以在nunjucks 帮助文档中查阅语法。一款主题最基本的目录结构应该是这样的:

- new_theme/
  - screenshot.png
  - package.json
  - index.html
  - post.html
  - page.html
  - tag.html
  - search.html
  - archive.html
  - template/ ## 非必须存在 ##
    - page_template.html

screenshot.png

固定名称,为该主题的预览图片,图片必须为 800x500 的 PNG 文件。

package.json

该文件用来存储主题的基本信息,其结构如下:

{
  "name": "new_theme",
  "version": "0.0.1",
  "description": "主题描述",
  "url": "主题地址",
  "preview": "主题预览地址",
  "tags": ["主题关键词", "主题关键词1"], 
  "configElements": [
    {
      "type": "选项类型",
      "name": "选项名称",
      "label": "选项标签",
      "help": "选项描述"
    },
  ]
}

nameversion 分别对应主题的名称以及版本号,name 应尽量唯一。如果你想要像默认主题一样,为主题添加一些自定义配置的话,你需要配置 configElements 属性。该属性用来配置主题选项,用户可以在后台设置。

configElements 属性的值必须为数组,数组每个元素为一个对象,其中 name 为该选项的英文名称,需要唯一且不能有空格label 为该选项的中文描述,help 为该选项的帮助内容。type 表示该主题选项的类型,支持 html, css, javascript, url, text, email, textarea, password, radio, checkbox, select 这些类型。

大部分的类型基本上只需要这四个属性就够了,但是 radio, checkboxselect 除外。他们额外需要增加 options 属性用来配置“单选/多选/复选”的选项,示例如下:

{
  "type": "radio",
  "name": "random",
  "label": "随机显示",
  "help": "随机显示可以随机显示背景图片",
  "options": [
    {"label": "", "value": 1},
    {"label": "", "value": 0}
  ]
}
{
  "type": "select",
  "name": "show_num",
  "label": "显示数目",
  "help": "显示图片个数",
  "options": [
    {"label": "0", "value": 0},
    {"label": "1", "value": 1},
    {"label": "2", "value": 2},
    {"label": "3", "value": 3},
    {"label": "4", "value": 4},
    {"label": "5", "value": 5}
  ]
}
{
  "type": "select",
  "name": "show_link",
  "label": "显示链接",
  "help": "仅显示勾选的网站链接",
  "options": [
    {"label": "Twitter", "value": "twitter"},
    {"label": "Github", "value": "github"},
    {"label": "Facebook", "value": "facebook"}
  ]
}

设置好后,在主题内可以通过 {{themeConfig.你的选项英文名字}} 来获取用户设置的值。

index.html

网站首页模板,模板中可以使用的变量可参考默认模板。

post.html

文章详情页模板,模板中可以使用的变量可参考默认模板。

page.html

默认的页面详情模板,模板中可以使用的变量可参考默认模板。

tag.html

标签显示模板,模板中可以使用的变量可参考默认模板。

search.html

搜索页模板,模板中可以使用的变量可参考默认模板。

archive.html

归档页模板,模板中可以使用的变量可参考默认模板。

template/page_template.html

template 文件夹内可以放置自定义页面模板,放置后用户可以在后台新建页面中选择该模板。最终该页面会以该模板进行渲染,而非之前的模板页面详情模板。

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.