| 0.9.8 |
|
|---|
#93 in #网站
275KB
663 行
可爱 是一个静态网站生成器。它生成 Rocket 网络服务器并构建 Markdown[^4] 源文件。它被创建出来提供极端配置和易于使用的配置 API，使用 TOML，这正是我们将在这里讨论的主要内容。
cuteconfig.toml
cuteconfig.toml 是用于存储配置设置的文件。当前版本的默认配置为：(最新版本)
# cuteconfig.default.toml
[misc]
latex = true # Add KaTeX support
html_lang = "en" # HTML Language
syntax_highlighting = true
[config]
# Write here your custom templates!
[misc]
此部分处理杂项设置，通常与预处理器和特定情况下的工具相关。
latex: 启用 LaTeX[^1] 方程式。html_lang: 改变起始<html>标签（例如 "es"<html lang="es">）。syntax_highlighting: 启用使用highlight.js的语法高亮。
[config]
本节用于存储用户提供的配置。它可以存储任何 TOML 值（字符串、整数、数组...）。
所有这些部分都可以使用 {{outer.*}}（例如 {{outer.misc.html_lang}}）在你的文档中，我们将在下一节中详细介绍模板。
前端内容
前端内容是您的 Markdown 内容之前的初始标题。此标题包含用于生成网页的一些配置选项。目前，唯一的必填字段是 title。
title：当前页面的标题。pageconf（可选）：用户提供的页面配置（键值对）。additional_css（可选）：需要额外渲染页面的 CSS 文件。 （index.css默认导入）
示例
# my_file.md
---
title: "My file"
---
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc est, semper non
maximus et, mattis in leo. Nullam luctus, ligula id venenatis consequat, ligula
odio convallis eros, sed scelerisque tortor elit vitae massa. Aliquam efficitur
tempus purus sit amet eleifend. Mauris vel ex iaculis, iaculis nisl id, finibus
justo. Morbi gravida vel velit eget ultricies. In orci purus, porta ut nibh
blandit, vestibulum lobortis augue. Vestibulum venenatis finibus tellus, sit amet
venenatis elit rutrum ut. Donec posuere ipsum efficitur tortor viverra dignissim.
Donec urna libero, molestie id libero vitae, bibendum rutrum leo. Praesent
suscipit tincidunt ultrices. Sed finibus neque blandit velit venenatis volutpat.
In id dui sit amet quam ullamcorper viverra. In rutrum ante sapien, et tincidunt
ligula dignissim id. Curabitur hendrerit sagittis orci, in rhoncus dui venenatis
sit amet. Nunc sed enim arcu.
在这种情况下，前端内容只包含 title，即 "My file"
模板
可爱 使用 Handlebars-rs[^3]，并为用户提供了 page 和 outer 的模板 API。
{{page.*}}
{{page.*}} 是您可以使用来使用页面配置的接口。例如，您可以使用 {{page.title}} 来访问页面的标题。
示例
# my_file.md
---
title: "My file"
pageconf: {
software-version: "0.7.2",
status: "beta"
}
---
Now I can use {{page.title}} to access this page's title.
Currently, our software is in version {{page.pageconf.software-version}}, that means that we're in a {{page.pageconf.status}} version.
这将渲染为
<!-- [...] -->
<body>
<div class="wrapper">
<div class="cutesidebar">
<ul>
<li><a href="introduction">Chapter 1: Introduction</a></li>
</ul>
</div>
<div class="main-content">
<p>Now I can use My file to access this page’s title.
Currently, our software is in version 0.7.2, that means that we’re in a beta version. </p>
</div>
</div>
</body>
<!-- [...] -->
{{outer.*}}
{{outer.*}} 是如果您想访问在 cuteconfig.toml 中找到的全局设置时要使用的接口。
示例
# cuteconfig.toml
# [...]
[config]
authors = [
"Alejandra González",
"Alejandra's cat, Keepy 🐱"
]
# [...]
# my_file.md
---
title: "My file"
---
Now I can list the authors of the page:
**Authors:**
{{#each outer.config.authors}}
- {{this}}
{{/each}}
这将渲染为
<!-- [...] -->
<body>
<div class="wrapper">
<div class="cutesidebar">
<ul>
<li><a href="introduction">Chapter 1: Introduction</a></li>
</ul>
</div>
<div class="main-content">
<p>Now I can list the authors of the page:</p>
<p><strong>Authors:</strong></p>
<p></p>
- Alejandra González
<p></p>
- Alejandra's cat, Keepy 🐱
<p></p>
</div>
</div>
</body>
<!-- [...] -->
源文件
一个正常的文件树看起来像这样
.
├── cuteconfig.toml
├── src
│ └── introduction.md
│ └── [Other .md files]
└── SUMMARY.toml
您的所有 Markdown 文件都位于 src 目录中；cuteconfig.toml 和 SUMMARY.toml 都位于根目录中。这是默认的树（由 cuteness init 生成）并且是开始编写内容的首选方式。
创建新文件时，您必须以 前端内容 开始文件编写，然后是您的文件内容。如 模板 中所述，您可以使用 Handlebars 模板。
SUMMARY.toml
SUMMARY.toml 是用于管理公开链接的文件。示例 SUMMARY.toml 文件（由 cuteness init 生成）如下所示
[[map]]
title = "Chapter 1: Introduction"
url = "introduction"
它包含一个表（map），这个表可以多次使用来定义不同的路由（由 [[ 双方括号 ]]）表示）。
[[map]]
title = "Chapter 1: ..."
# [...]
# Another page
[[map]]
title = "Chapter 2: ..."
# [...]
[[map]] 表包含一些字段，如 title 和 url，以下部分将解释它们。
-
title：页面的标题，这将被用于诸如 HTML 的头部的<title>标签或在侧边栏中的情况。 -
url：页面的 URL，即如果源页面在 "<root>/src/my_file.md"，则写入 "my_file"。
(此处为最新版本)
服务器路由和显示给用户的路由不需要相同。
子命令
init
cuteness init 是用于初始化一个空目录的命令，以便写入。它将创建
src目录。introduction.md在src中，包含一些 默认内容。SUMMARY.toml在根目录中，包含 默认内容。cuteconfig.toml在根目录中，包含 默认内容。
您可以从编写 introduction.md 开始，然后执行 cuteness build，执行 cargo run --manifest-path <output directory, default: www>/routing/Cargo.toml 并访问 https://127.0.0.1:8080/introduction
build
cuteness build 用于构建项目，它将在输出目录中创建包含构建版本（使用所有您的配置）的 src 目录。如果在 src/styles 目录中有 .sass 文件，它也将编译这些文件。
setup
cuteness setup 是一个一次性命令，用于从网络获取所有必要的模板文件。它需要网络连接。您可以将它视为增强的 git clone，它只克隆必要的文件。
注意：此命令将在您的 Cargo 主目录（通常为 Unix 系统上的 ~/.cargo/）中创建一个名为 cuteness-config 的目录，并将所有内部配置存储在那里。（不要手动编辑。）
update
cuteness update 将更新内部模板和样式到最新版本；你可以将其视为增强版的 git pull。
clean
cuteness clean 将删除输出目录（默认：www）。通常情况下不需要这么做。
uninstall
cuteness uninstall 将删除存储在 <CARGO HOME>/cuteness-config/ 的内部模板和样式文件。
这不会卸载二进制文件，你需要使用 cargo uninstall cuteness 来卸载二进制文件。在执行此操作之前需要先运行此子命令以确保完全卸载。
help
cuteness help 显示帮助信息。
样式
样式文件存储在 src/styles 中，可以通过在页面前端元数据中使用 additional_css 可选键来按页面导入。
特殊的内置 index.css 文件始终被导入，该文件包含正确显示页面的基本布局选项。你可以在这里查看 index.css 的 Sass 源代码 here。
使用 Sass
你可以将 Sass 用作文件的预处理器，只需在安装二进制文件时激活 sass 功能（默认启用）并将你的 .sass 文件存储在 src/styles 中，就像其他 .css 文件一样。它们将与 cuteness build 一起编译。
不使用 Sass
几乎相同，只需将你的 .css 文件定位在 src/styles 中，它们将不会被编译，但只会被复制到输出目录。
路由
当使用 cuteness build 时，将生成一个包含一些静态文件和简单 web 服务器的输出目录，你可以通过访问 https://127.0.0.1:8080/
由于项目仍在开发中，关于使用互联网上实际服务器的努力还非常遥远。
预处理器
在写入之前，文件内容会被预处理器处理，这些预处理器用于将“直引号”更改为“弯引号”，或将表情符号代码 ":cat:" 转换为实际的表情符号 🐱。这些预处理器会自动应用，不应该引起任何问题。
[^1]: 工具专门使用 KaTeX，专注于方程式。
[^3]: Handlebars-rs 使用 Handlebars 模板语言
[^4]: 具体来说，我们的解析器 (pulldown-cmark) 使用 CommonMark 规范。
[^5]: 一些将生成的 web 服务器移植到 Rust 的想法。由于项目尚未达到 v1.0 版本，这可能在将来发生变化。
功能
功能文档可以在渲染的 rustdoc 页面上找到。可以通过 cargo doc 访问。
许可证
本项目使用的是 GNU通用公共许可证v3.0。有关许可的更多信息请参阅 LICENSE。
贡献
所有贡献都受到热烈欢迎！一份非常有用的贡献指南可以在 CONTRIBUTING.MD 找到。
依赖项
~12–23MB
~318K SLoC