JasperXu's 笔记本
 
发布时间: 2021-04-28 02:00
修订时间: 2021-04-28 04:06

一个静态文档站点生成器

自己写的一个静态网站生成器。

1. 目录说明

source 文件夹中的文件会构建到 docs 文件夹中。(为了方便使用 GitHub-Page)

source/lib/scss 中的文件会被构建到 docs/lib/css 文件夹中。(使用sass进行编译)

2. 特殊文件说明

目录中有5个特殊的文件(不存在则向上级查找):

_index.html :模板页,所有的Markdown文件都会由这个模板进行填充。

_navbar.md :顶部导航栏,会自动生成多级菜单,直接显示在页面顶部。

_sidebar.md :左侧导航栏,会自动生成多级菜单,文章页面则会显示到左侧。

_coverpage.md :封面页,不显示侧边栏,有特殊样式。构建后会生成为 index.html

README.md :目录首页,按普通文章构建。构建后会生成为 index.html

3. 文章内参数说明

使用 YAML Front Matter 定义文章的属性:

直接可使用的属性如下:

date : 发布日期,创建文章的日期,会显示在文章的顶部左侧。

update : 修订日期,最后修改文章的日期,会显示在文章顶部的右侧。当设置为 modify-time 是会自动读取文件的最新修改日期。

keywords :网页的keywords,会填充到页面的 meta 中。方便SEO。

description :网页的description,会填充到页面的 meta 中。方便SEO。

tags :用于网站自己的标签,目前页是写入到页面的 meta 中。

categories :用于网站自己的分类,目前页是写入到页面的 meta 中。

可以在这里自行定义任何名称,_index.html 中的输出规则如下:

  1. 包含 date 会格式化为日期。
  2. _index.html 中使用 { inject-你的属性名 } 进行输出。

4. 文章内的说明

4.1. 链接

  • 当前文章中可以使用相对路径,但是还是推荐使用绝对路径。例如:../exp , abc/exp
  • 链接可以不包含后缀 .md.html ,但是还是推荐使用 .md 后缀。例如:exp.md , exp , exp.html 这三个是相同的链接。(注:不包含后缀时文件名中不能出现 . 否则无法链接)
  • 外链会自动添加 target="_blank" 属性。

4.2. 图片

  • 文章中可以使用相对路径,推荐使用相对路径。
  • 图片支持缩放,点击后放大。使用 medium-zoom 进行的支持。
  • 可以为img增加属性。(具体如下)
![](images/WX20210412-203510.png "这个是标题 {#img1 .imgClass height=50px width=100px}")
设置img的 title 为:这个是标题
设置img的 id 为:img1
设置img的 class 为:imgClass(可设置多次)
设置img的 height 为:50px
设置img的 width 为:100px

4.3. 标题

  • 可以为标题增加属性。(具体如下)
  • 会在标题前面生成一个和标题id完全相同的<a class="hiddenanchor">的标签,用于给文章定位的暗锚。
  • 会在标题内部生成一个指向本标题的<a>标签。
# H1的标签 {#heading1 .heading1Class attr=aaa}
设置标题的 内容 为:H1的标签
设置标题的 id 为:heading1
设置标题的 class 为:heading1Class(可设置多次)
设置标题的 attr 为:aaa(可以设置为你需要设置的内容)

4.4. Code (行内代码)

  • 支持tex。使用katex进行的支持。需要$进行标识。
 ` $ 这里支持tex $ ` (需要去掉 ` 和 $ 中间的空格)

4.5. Code (多行)

  • 支持tex。使用katex进行的支持。需要在代码块中的开头和结尾都用两个$进行标识。
  • 支持编程语言的高亮显示。使用的prismjs。
​```
$ $ (以两个 $ 开头,需要去掉两个 $ 中间的空格)
这里支持tex
(以两个 $ 结尾,需要去掉两个 $ 中间的空格)
$ $
​```

4.6. Tab 支持

都是以注释的方式进行标注<!-- -->

tabs:start 是开始。

tabs:end 是结束。

这里是 Windows Tab 的内容。
tab:Windows

这里是 macOS Tab 的内容。并且添加了一个苹果的图标。
tab:<i class="fab fa-apple fa-2x"></i> macOS

这里是 Linux Tab 的内容。
tab:Linux

4.7. 支持 Bootstrap 的所有样式和控件

基于 Bootstrap 开发的模板,所以支持全部内容。4.6.0 版本

4.8. 支持 font awesome 的图标

添加了 font awesome free 的支持。fontawesome-free-5.15.3 版本

4.9. 支持 gitalk

添加了 gitalk 的支持。1.7.2 版本 将所有的评论都集合到一个 Issue 中。

5. 生成设置

jxdocs.config.json 中的设置:

formatUpdated :日期的格式化字符串。

maxLevel :生成文章目录时选取的最大标题级别。(默认4,选取到h4)

其他选项目前都无法使用。

6. 命令说明

npm run clear : 清理 docs 目录。

npm run serve : 启动 docs 中的网站。

npm run buildscss :构建 scss 到对应的 css 目录。

npm run build :构建 source 到 docs 目录,不包含scss。

npm run buildall :清理 docs 后全部构建。

npm run start :全部构建后运行,会先清理docs。

7. TODO

  • 插件系统(BefourRender,BefourInject,BefourSave 主要是这3个事件)
  • 生成设置(其他属性无效,需要让这些属性生效)
  • 站内检索。!!!
  • 代码及时预览(jsfiddle 集成)
  • 文件修改的监控,无需命令构建,serve后监视文件修改。!!!