MWeb 官方 Telegram 群已建立,点击可查看
MWeb 3.2.8 及以下版本升级到 3.3.1 版本说明

文档 - 自定义或制作自己的静态网站模板


如果当前使用的网站模板无法满足自己的需求,则可以做一些自定义,或者完全重新制作自己喜欢的网站模板。不管是重新制作还是自定义,都是有一定的技术要求的,首先必须要懂 HTML、CSS,然后,再懂 javascript 就更好了。继续阅读前,请确保你已看过MWeb 生成静态网站 & 博客这篇文章。

MWeb 静态网站模板生成过程

不管是自定义还是制作,都要了解 MWeb 静态网站的生成过程。要明白生成过程,首先可以看一下 MWeb 常规的网站模板的文件结构,结构如下:

  • asset -- 文件夹,主题所有要用到的东西,图片、CSS、JS 等等都放这里
  • header.html -- 页面的头部
  • footer.html -- 页面的底部
  • sidebar.html -- 页面的侧边栏
  • category.html -- 分类页所使用的模板
  • tags.html -- 标签页所使用的模板
  • archives.html -- 归档页所使用的模板
  • post.html -- 文档不选中 是否页面(Is Page) 所使用的模板
  • page.html -- 文档选中 是否页面(Is Page) 时所使用的模板
  • page-index.html -- 自定首页模板
  • atom.xml -- RSS 所使用的模板
  • sitemap.xml -- 网站地图所使用的模板

你可以随便查看内置的网站模板的结构,右键网站分类,选择编辑,在模板那里,点编辑... 按钮,如果是 MWeb 自带的模板,请选择复制当前的模板到自定义模板文件夹...,复制出来,再选择 打开自定义模板所在的文件夹... 则可。注意:如果要修改 MWeb 自带模板,首先要先使用复制当前的模板到自定义模板文件夹...复制到自定义模板的位置,才能修改,如下图。

文章页的生成过程

不选是否页面(Is Page)选项时,生成文章页的顺序为:header.html + post.html + sidebar.html + footer.html。

选中了 是否页面(Is Page) 选项后,生成文章页的顺序为: header.html + page.html + footer.html。

更高级的用法:

做网站经常要定制一些页面,在文档中,选中了 是否页面(Is Page) 选项后,如果要自定这页,可以新增一个名称为:page-{HTML 文件名}.html 的模板页面,这样生成文章页的顺序会变为:header.html + page-{HTML 文件名}.html + footer.html。{HTML 文件名} 说的就是下图的 HTML 文件名: 所填入的名字。

自定义首页例子

在 MWeb 的静态网站生成中,可以自由指定一个文档为首页,方法非常简单,在 HTML 文件名: 中填入 index 即可,这样生成时,就会生成 index.html 页了,如下图。

如果要自定义,比如说像 MWeb 官网 https://zh.mweb.im/index.html 这样的首页,则是要自定义了,方法很简单,在主题文件夹里新增一个名为:page-index.html 的页面即可。如上面所说,当生成 index.html 这个 页面时,模板顺序会变成:header.html + page-index.html + footer.html。

各分类的文章列表页的生成过程

分类页生成的顺序为:header.html + category.html + sidebar.html + footer.html。 其中,可以自定义任何一个分类的 category.html 模板。如下图,在网站的任何一个子分类中,右键 - 编辑,都可以设置 HTML 文件名,下图为 help,则会生成 help.html。

而 MWeb 在生成分类页的 HTML 时,会判定是否存在:category-{HTML 文件名}.html 的模板文件,如果存在,则会优先使用 category-{HTML 文件名}.html 模板文件。上图就是定制了一个 category-help.html 的模板文件,这样生成的顺序变为:header.html + category-help.html + sidebar.html + footer.html。最终效果如:https://zh.mweb.im/help.html,这就跟一般的分类不一样了。

其它页的生成过程

其它页面生成没有像文章页和分类页的自定模板规则,下面列出一下:

  • 归档页(archives.html): header.html + archives.html + footer.html
  • 标签页: header.html + tags.html + sidebar.html + footer.html
  • 网站地图:sitemap.xml
  • 网站 RSS:atom.xml

自定义网站模板

上面已经介绍了网站的生成过程,了解之后就可以做一些小的自定义了,在这之前,要先了解 MWeb 所使用的模板语言,这个语言非常简单,你可以参考 MWeb 自带的网站模板,一般就能看懂了。之后可以参考所有用法例子,请看:模板语言例子.txt

一般可以直接修改模板文件来做小的自定义,因为模板文件都是 HTML,懂 HTML 即可。或者修改样式,同样,懂 CSS 即可。
如果要做更方便一点的自定义,比如说为网站模板增加一个广告位,这个广告经常换,但是我不想总是修改模板。这种需求可以用 MWeb 的网站扩展来解决。如下图为网站扩展设置界面,这里其实是变量,这些变量,在所有模板页都可以访问到。下页以增加 global_notice 这个变成为例子说明。

增加按钮,然后设置如下图:

增加了 global_notice 变量后,可以在 网站扩展设置 中设置这个变量的值,如下图:

这样,就可以在所有模板页中以 {{ext_global_notice}} 这个语法,输出设置了的值。

特别注意:在修改了网站模板之后,要生成网站时,请使用清除并重新生成网站这个功能,这样才会生效。

同样,可以看到还有文档扩展,文档扩展用法一样,但是只针对文档,设置是在文档的大纲视图最底下。

你们可否注意到,有些变量前面有个锁,这个是表示这个变量是网站模板自带的变量,不可以编辑的。意思是,扩展变量除了在上面增加外,还可以在网站模板中增加。增加方法是修改相关的 .json 文件。请参考:site-mweb-bulma 这个模板,在这个模板里,有一个名为 extensions 的文件夹,这里面有三个 .json 文件,其中,网站扩展 的变量,使用的是 site.json 文件,文档扩展 的变量,使用的是 document.json 文件。

制作自己的静态网站模板

了解了 MWeb 的静态网站生成过程,也了解了模板变量的使用和网站扩展、文档扩展的使用方式,就可以制作自己的静态网站模板了。建议的方法是,参考 MWeb 自带的三个模板:site-mweb-bulma、site-mweb-simple 和 site-foundation-book。找到想要的功能,然后查看相关写法即可。下面介绍一下这三个模板。

  • site-mweb-bulma 这个模板包括了比较完整的 MWeb 网站模板的功能,比如说文章列表中显示自定义的图片和提要,列出所有分类,所有标签。
  • site-mweb-simple 这个是极简的模板,不使用标签功能。
  • site-foundation-book 这个是制作帮助文档类型的网站。

制作网站模板之前,还要了解 extensions 文件夹中的三个配置文件的作用,这里分开说明:

  • config.json 这个是配置是否生成相关页面用的,有四个变量设置。
    1. isCreateCategoriesPages 如果设置为 true,则会生成分类列表页面,否则不会生成。这个一般要设置为 true,除非是极极简的模板。
    2. isCreateTagsPages 如果设置为 true,则会生成标签列表页。这个看需要,比如说 site-mweb-simple 不使用标签功能,所以设置为 false。
    3. isCreateTreeVars 这个一般是像 site-foundation-book 这种模板才会设置为 true,这个设置为 true 后,会在每个分类变量中,附带这个分类的所有文章的变量。
    4. isCreateArchivesVarsToIndex 这个如果设置为 true 的话,会把归档页的所有文章的变量传到 首页中,归档页的特点是有所有文章列表的变量。这个仅用在自定义首页并且要求在首页显示所有文章的需求。
  • site.json 网站扩展 的变量。
  • document.json 文档扩展 的变量。

在介绍 MWeb 静态网站的所有变量之后,还要说说另一个,就是 MWeb 的LaTeX、代码高亮和画图功能。在制作自己网站模板时,建议顺手增加支持这些。方法非常简单,每一个 MWeb 自带的网站模板,都有一个 section-chart-support.html 文件,复制这个文件到你的模板中,然后在 footer.html 中使用 <!-- include(section-chart-support.html) --> 引入即可。另外,代码高亮使用的是 prism.js,这个模板只引入了在 asset 中的 prism.js 文件(所以还要保证 asset 中有 prism.js),并没有相关的 css 样式,这个需要自己去 https://prismjs.com 选择相应的样式,由于都是 CSS,所以可以直接加到模板中。具体可以参考系统自带的模板。

MWeb 静态网站所有变量参考

所有模板页面都会传入的变量

变量名称 说明
siteURL 网站设置中的网站网址
siteDomain 网站的域名
siteName 网站的名称
pageTitle 网站的标题
siteDes 网站的描述
lastBuildDate 网站最后生成时间
siteOther 网站设置中的 网站其它代码
siteMenu 网站菜单,数组,数组对象例如:{name: "Home", url: "index.html", className: "", target: "self"}
recentPosts 数组,数组的对象例如:{title: "标题", url: "post_url.html"}
allCategories 数组,数组的对象例如: {name:"分类",url:"cat.html",count:2}
allTags 数组,数组的对象例如: {name:"标签",url:"tag_lable.html",count:2}
categoriesTree 二层分类树,数组,数组的对象为 {name:"分类", url:"cat.html", count:2, children:[ {name:"",url:"",count:3} ... ]}。请参这个网址

以上的变量只是固定的变量,此外,还要加上网站扩展的自定义变量。文档扩展的变量使用为 ext_ + 扩展变量名,使用方式,请参考这个网址

文档对象变量

这个文档对象变量,下面说明会用到,如果提到文档对象变量,说的就是这个。

变量名称 说明
title 文章的标题,通常为第一行
desContent 文章的HTML格式的描述,如果文档中没有 <!-- more --> 则跟 content 一样
desContentTextOnly 文章的纯文字描述,不带 HTML
content 文章的内容
date 文章的时间,格式按网站设定,默认为:2014/10/24
dateGTM 文章的时间,格式为 2014-10-24T13:54:03GMT+08:00
artDate 文章新增的时间,格式按网站设定,默认为:2014/10/24
cats 文章分类的数组,数组的对象例如: {name:"分类",url:"cat.html"}
tags 文章标签的数组,数组的对象例如: {name:"标签",url:"tag_name.html"}
readMore 文章中是否有 <!-- more -->
url 文章的网址
chart_flowSeq 文档中是否带 flow 或者 sequence 画图,有值并为 "y" 是为带。
chart_VIZ 文档中是否带 VIZ 画图,有值并为 "y" 是为带。
chart_ECharts 文档中是否带 ECharts 画图,有值并为 "y" 是为带。
chart_mermaid 文档中是否带 mermaid 画图,有值并为 "y" 是为带。
chart_codeblock 文档中是否带代码块,有值并为 "y" 是为带。
chart_LaTeX 文档中是否带 LaTeX 数学公式,有值并为 "y" 是为带。
chart_scripts 文档中画图的支持脚本。
  1. 以上 chart_flowSeq,chart_VIZ 等等的使用方式,请参考自带模板的 section-chart-support.html 文件,线上查看请点此
  2. 以上的变量只是固定的变量,此外,还要加上文档扩展的自定义变量。文档扩展的变量使用为 ext_ + 扩展变量名,请参考这个网址

生成单篇文章的页面传入的变量

变量名称 说明
post 对象为文档对象变量
postNav 字典,带有nextprev两个对象,对象例如:{title: "标题", url: "post_url.html"}

参考模板:https://github.com/oulvhai/MWeb-Themes/blob/master/octopress/post.html

生成单篇文章选中 Is page 的页面传入的变量

变量名称 说明
posts 数组,数组的对象为文档对象变量
post 对象为文档对象变量

参考模板:https://github.com/oulvhai/MWeb-Themes/blob/master/mweb-greyshade/page-index.html

分类页面的变量

变量名称 说明
posts 数组,数组的对象为文档对象变量
currentCat 当前分类,对象例如:{name: "分类名", url: "cat_url.html"}
prevPageUrl 上一页的网址
nextPageUrl 下一页的网址

参考模板:https://github.com/oulvhai/MWeb-Themes/blob/master/site-mweb-bulma/category.html

标签页面的变量

变量名称 说明
posts 数组,数组的对象为文档对象变量
currentTag 当前分类,对象例如:{name: "标签名", url: "tag_url.html"}
prevPageUrl 上一页的网址
nextPageUrl 下一页的网址

参考模板:https://github.com/oulvhai/MWeb-Themes/blob/master/site-mweb-bulma/tags.html

归档页 archives.html 的变量

传入的变量:

变量名称 说明
posts 数组,数组对象请参考下表
变量名称 说明
year 文章年份
title 文章标题
url 文章网址
cats 文章分类的数组,数组的对象为文档分类对象变量
date 文章的时间,格式按网站设定,默认为:2014/10/24
dateMonth 文章月份
dateDay 文章日期
dateYear 文章年份
dateGTM 文章的时间,格式为 2014-10-24T13:54:03GMT+08:00
artDate 文章新增的时间,格式按网站设定,默认为:2014/10/24

此外,还会传入文档扩展的变量。
参考模板:https://github.com/oulvhai/MWeb-Themes/blob/master/site-mweb-bulma/archives.html

sitemap.xml 的变量

传入的变量:

变量名称 说明
archives 数组,数组对象请参考下表
pages 数组,数组对象请参考下表
nowDateGTM 当前时间
变量名称 说明
title 文章标题
url 文章网址
date 文章的时间,格式按网站设定,默认为:2014/10/24
dateGTM 文章的时间,格式为 2014-10-24T13:54:03GMT+08:00
artDate 文章新增的时间,格式按网站设定,默认为:2014/10/24

参考模板:https://github.com/oulvhai/MWeb-Themes/blob/master/site-mweb-bulma/sitemap.xml

atom.xml 的变量

读取的模板:atom.xml
传入的变量:

变量名称 说明
posts 数组,数组对象为文档对象变量

参考模板:https://github.com/oulvhai/MWeb-Themes/blob/master/site-mweb-bulma/atom.xml