20ful 中文文档教程

Question

20ful

有意义的静态站点生成器。

Installation

$ npm init -y
$ npm install 20ful

Quick start

$ mkdir -p src/html
$ cat > src/html/hello.md
---
index: true
---
# Hello world!
^D
$ 20ful

您还可以查看示例项目。

Running and command line options

20ful 构建 编译您的输入文件并退出

20ful watch 编译你的输入文件并观察变化

20ful serve 以上所有，并启动静态服务器，在更改时重新加载它 与浏览器同步。 这是默认值。

20ful 代理 改为启动 HTTP 代理服务器并连接到给定端口。 这个有用 如果您的站点不是那么静态并且您已经有一个服务器在运行，但是 想观察前端文件的变化。

--port

在 server 或 proxy 模式下监听的端口。 默认值为 3000。

What it does

生成器接收您的输入文件，可能应用转换，并且 写出来。

Directory structure

把你所有的东西都放在 src/ 中。 它将被编译并放入 _site/，保留目录结构。 忽略点文件。

文件夹 src/html/ 是特殊的，“html”部分将在结果中被剥离 路径，对于编译成 HTML 文件名的文件做成一个文件夹，内容 放在index.html里面。

source	destination
src/server-config	_site/server-config
src/assets/css/main.styl	_site/assets/css/main.css
src/html/.git/	ignored
src/html/mypage.md	_site/mypage/index.html

这也意味着，如果您创建两个路径名不同的文件 在 html/ 部分，只有其中一个会到达输出位置，所以不要 去做。

Conversions

生成器原生支持以下转换：

• for HTML: Markdown (.md), Pug (.pug), Nunjucks (.njk)
• for CSS: Stylus (.styl), Sass (.scss, .sass)
• for JavaScript: LiveScript (.ls)

文件类型由其后缀决定。 所有其他文件都按原样复制到 它们的目的地，包括纯 HTML、CSS 和 JavasScript。

任何文件都可以具有 YAML 格式、--- 分隔的前部内容 (FM)，即 处理后剥离。 某些行为由前端数据定义。

Front matter attributes

template: string

该文件是一个命名模板，通常为 pug 或 njk。 没有指定 存储模板的位置，只要它们在 src 中，也不存在 是您必须给它们的任何特定文件名。 以下模板 变量是特殊的：

body

使用此模板的渲染文件。

toc

中的目录或导航。 从 toc 属性构建， 见下文。

css

引用 CSS 文件的 属性集（如果启用了缓存清除）。 见下文。

js

引用 JS 文件的

所有特殊变量都包含 HTML，因此必须在不安全模式下传递。 默认模板 system 始终存在，并且只渲染主体，因此您 可能想将您的第一个模板命名为“系统”。

layout: string

该文件使用命名模板呈现。 可能的值：

• some name named template is used.
• none no template is used
• (attribute not present) template "system" is used

index: boolean

如果设置为 true，此文件将写入输出中的顶级 index.html 目录。

toc: object

对象，描述目录条目。 它的属性：

• key: (visible label in the TOC link)
• order: (entries are sorted using this value)

目录是分层的，遵循目录结构。 有一个 有用的目录组织你的文件：

  My-Stories.md           [FM]  toc:
                                   key: My cool stories
  My-Stories/
     Cool-story-1.md      [FM]  toc:
                                   key: First cool story
                                   order: 10
     Another-story.md     [FM]  toc: ...

没有必要（也没有办法）指定父母，你可以重新安排你的 页面只是移动它们，TOC 将自动重建，并且 将呈现为有序列表：

1. My cool stories

bust-cache: boolean

如果设置为 true，为这个 CSS 或 JS 文件启用缓存清除。 缓存破坏 通过自动向文件名添加哈希后缀来完成，更改为 文件内容变化。 模板变量 css 和 js 将具有整个 您需要逐字传递的 和

对于编译为 CSS 的所有文件，css 变量存储一系列 link tags:

<link rel=stylesheet href='/path/filename-34856.css'><link ...

对于编译成 JavasScript 的所有文件 js 变量存储一系列 script 标签：

<script src='/path/filename-51536.js'><js ...

在 pug 模板中，放置 | !{css} 和 | !{js} 在头部。

order: number

这控制了缓存破坏的 css 和 js 变量中标签的顺序。

options: object

传递给编译器的选项，例如 main.ls 可能看起来是：

---
options:
   bare: true
---
f = a >> b

并且 LiveScript 不会生成顶级包装器。

ignore: boolean

如果设置为 true，则跳过此文件。

Config file

从 ./20ful-config.yaml 中读取用户配置。 默认值是：

source:  src
outroot: _site
markdown-it-plugins:
  markdown-it-mark: true
  markdown-it-multimd-table:
    headerless:   true
    multiline:    true
    rowspan:      true

Markdown-it-plugins 就是它们看起来的样子。 添加 markdown-it 插件：

• install markdown-it-plugin-<name>
• mention it in the config (false to disable)

如果插件采用选项，则将它们作为子键提供。

Motivation

人们为像这样简单的事情付出的努力让我感到惊讶 站点生成器，同时因缺乏明显的 功能，例如 CSS 的预处理。

这个项目几乎没有那么宏伟（截至目前不到 350 行代码）， 它仍然涵盖了最基本的需求。