Lib.rs

› Web 编程
#静态网站生成器 #toml-config #web #config-file #site #rocket-web #website

nightly bin+lib cuteconfig

Cute 静态网站（+ 服务器）生成器，附带大量插件 :3

由 Alejandra González，TheBearodactyl

6 个版本

1.0.0 2023年11月23日
0.9.10 2023年11月23日
0.9.8 2023年3月28日

#25 in #site

每月下载量 21

GPL-3.0 许可证

275KB
663 行

Cuteness logo

crates.io docs.rs

Cute 是一个静态网站生成器。它生成一个 Rocket 网络服务器，并构建 Markdown[^4] 源文件。它被创建用来提供极端配置和易于使用的配置 API，使用 TOML，这是我们在这里要讨论的主要内容。

cuteconfig.toml

cuteconfig.toml 是用于存储配置设置的文件。当前版本的默认配置是：（最新版本）

# cuteconfig.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，即 "我的文件"

模板化

可爱度 使用 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的head部分或侧边栏中的 <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，并且可以通过在每个页面的 front-matter 上使用 additional_css 可选键来按页面导入。

特殊的内置 index.css 文件始终会被导入，该文件包含用于正确显示页面的基本布局选项。您可以在 这里 查看代码的 Sass 源文件。

使用 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–22MB
~306K SLoC