keystone ssg

警告

Keystone 现在看起来已经过时了，我建议您看看 Astro 或 Vite。

---

为什么选择梯形？

Keystone 是一款静态站点生成器，非常适合快速构建小型网站。无需设置，默认情况下会启用一系列方便的功能。

特征

• 轻松安装和设置，只需一个命令即可开始使用
• 自动刷新开发服务器
• 使用模板和可重用的部分/导入，带有插槽
• 自动路由，只需上传/public即可开始
• 默认启用 Babel、SCSS 和 Markdown 支持，开发模式下的源映射
• JS 和 CSS 缩小和捆绑（使用 Rollup）
• 动态链接加载（无需重新加载页面）
• 搜索索引文件生成器，方便网站搜索

入门

安装

创建一个新目录并运行以下命令来设置 Keystone、package.json 和 git。需要节点 14.xx。

 $  npm install keystone-ssg

太棒了，你已经安装好了！

开发服务器

启动 Keystone 开发服务器，然后访问 http://localhost:8080 查看示例网站。

 $ npm run dev

构建项目

运行命令后，项目将在/public文件夹中构建，准备上传。

 $ npm run build

建立您的网站

Keystone 项目中有六个重要的目录，每个目录都有自己的用途：

页数

页面文件夹中的每个 HTML .html和 markdown .md文件都对应于您网站上的一个页面。这里的示例项目中有两个文件，尝试打开index.html 。自动路由将在运行npm run build时将文件捆绑到/public文件夹，如下所示：

 /pages/index.html   ->  /public/index.html
/pages/example.md ->  /public/example/index.html

您可能已经注意到， index.html具有以下标记： <_template basic.html /> 。这会将index.html的内容放置在位于/templates/basic.html的开槽模板文件中。这种自定义 HTML 标记格式也适用于.md文件。

模板

模板可以与/pages一起使用，为您的页面提供现成的框架。在模板文件中使用<_slot />标记为您的内容提供入口点。打开/templates/basic.html并查找：

 < _var title default="Keystone default title" />

这是模板文件中名为title的变量槽，具有可选的默认值。

使用以下内容作为/pages内的模板标签将允许您从内容页面将自定义值输入到模板中：

 < _template basic.html title="A custom title" /> 

成分

/components夹仅用于可重用组件。 <_import>标签用于将组件导入到其他 HTML 文件中，其中的一个示例位于/templates/basic.html中。

 < _import header.html />

在首先捆绑源代码之后， <_import>标签还可以用于导入任何其他类型的文件（JS、SCSS 等）的内容。

源代码

将 Javascript 文件放置在/src文件夹中。以下标签将转换为常规<script>导入标签，链接到您的文件/src/main.js ：

 < _script main.js />

完全支持 ES6 导入，生成的文件将使用 Babel 进行转译，与 Rollup 捆绑并缩小。

风格

/styles文件夹用于您的 CSS/SCSS。以下标记将转换为常规<link> css 导入标记，链接到已编译的/styles/main.scss文件：

 < _style main.scss />

完全支持所有node-sass功能，包括@import 。

资产

静态资源放置在这里，即字体、图像、图标。这里的所有内容都会转移到根目录中相应的文件夹中，例如：

 /assets/favicon.ico -> /public/favicon.ico
/assets/fonts/fontname.ttf -> /public/fonts/fontname.ttf

笔记

Keystone HTML 标签

• 每个自定义 Keystone HTML 标记都可以在 HTML 文件中的任何位置使用，甚至在其他 HTML 属性中（除了其他 Keystone 标记之外）。
• 或者，对于所有自定义 Keystone 标记，您可以使用 src 属性来定位任何文件夹中的文件： <_template src='myfolder/myfile.html' /> 。
• 所有路径都相对于包含package.json的文件夹，除非您想访问项目外部的文件，否则不要使用开头的斜杠。
• Keystone HTML 标记属性可以使用“单”、“双”或“反引号”引号。

动态加载

• 动态加载获取本地网站链接并用新页面替换当前页面的内容，无需重新加载和切换页面。
• 启用动态加载时，使用后退按钮时不会保存页面状态（例如输入值、滚动位置）。
• 单击链接时， .keystone-page-loading类将设置为display: block 。如果该类在 CSS 中设置为display: none ，则可以使用它来创建加载指示器。
• 在 keystone.config.js 中禁用动态加载。

搜索索引生成器

• 搜索索引生成器在根目录中生成一个文件search.json 。这是一个 JSON 数组，其中包含每个页面的对象，列出页面的文本内容、标题和路径。
• 所有 HTML 标签都会从页面中剥离，只保留和存储文本。
• 该文件可以通过网站搜索功能获取和查询，以轻松找到哪个页面包含哪些内容。
• 在 keystone.config.js 中禁用搜索栏助手。

各种各样的

• public文件夹被 Git 忽略，如果您希望使用公共行将其提交到 Git，请从.gitignore中删除public行。

更新梯形校正

• 将package.json中的版本号替换为您要更新到的版本，然后运行npm install keystone-ssg ，以进行快速升级。

应用程序编程接口

标签

标签	描述	属性
<_template>	将当前文件导入到模板文件中的<_slot>中	[文件名],[变量名],src
<_slot>	在模板文件中用作导入文件的入口点	没有任何
<_var>	在模板文件中使用，替换为取自<_template>的变量	[变量名称]，默认
<_import>	导入一个组件	[文件名]，src
<_script>	创建链接到捆绑脚本的<script>标记	[文件名]，src
<_style>	创建一个链接到捆绑的 css 文件的<link>标签	[文件名]，src

NPM 命令

命令	描述	输出差异
npm run dev	构建用于开发的网站，然后启动 Keystone 开发服务器。	生成内联源映射。 开发服务器脚本已注入。
npm run build	构建用于生产的网站。	捆绑包被压缩和缩小。

配置文件

配置文件是keystone.config.js

选项	描述	默认
动态链接	在您的 Keystone 网站上启用动态加载的本地链接，无需刷新	真的
搜索文件	在根目录生成search.json	真的
索引路径	您网站的根目录	'/'
港口	开发服务器端口，本地主机： 8080	8080
端口Ws	用于开发服务器的第二个端口	8081
开发服务器IP	开发服务器的位置，本地主机：8080。替换为您设备的本地 IP 以查看本地设备上的开发服务器（例如：“192.168.1.103”）。	'本地主机'
看过	Keystone 开发服务器监视的目录，在编辑文件时将强制重新编译和页面刷新	['模板'、'页面'、'资产'、'组件'、'src'、'样式']
建造	内容页面目录	“页面”
服务	包含生成的网站的目录	'民众'
完全重新编译	在开发模式下每次文件更改后强制完全重新编译所有文件	错误的

默认目录布局

 | empty-keystone-project
--| .git/
--| assets/
--| components/
--| pages/
--| src/
--| styles/
--| templates/
--| keystone.config.js
--| package.json
--| package-lock.json

插件错误

如果安装并运行示例后出现 PLUGIN_ERROR，这是 Babel 问题，请运行以下命令来修复它：

 npm install @babel/core @babel/preset-env --save-dev