15 个版本

0.3.8	2024 年 4 月 23 日
0.3.7	2024 年 4 月 19 日
0.2.1	2024 年 4 月 4 日
0.2.0	2024 年 3 月 27 日
0.1.5	2024 年 3 月 24 日

#580 in Web 编程

1,205 每月下载次数

MIT 许可证

83KB
626 行

轻松创建博客

迭代地将一组 Markdown 文件转换为相应的 HTML 模板。

安装

轻松创建博客作为二进制文件和库都可在本包中找到。

在这两种情况下，请确保您已安装 cargo。

二进制

打开您的终端，并运行以下命令。

$ cargo install blogs-md-easy

库

运行以下命令以更新您的 Cargo.toml。

$ cargo add blogs-md-easy

用法

以下为程序二进制的帮助页面，如果您想阅读库的文档，它可在 docs.rs 上找到。

Iteratively convert a collection of Markdown files into a respective HTML template.

Usage: blogs-md-easy.exe [OPTIONS] --templates <FILES>... --markdowns <FILES>...

Options:
  -t, --templates <FILES>...  HTML template that the Markdowns will populate
  -m, --markdowns <FILES>...  List of Markdown files ending in .md
  -o, --output-dir <DIR>      Output directory, defaults to the Markdown's directory
  -a, --allow <RULES>...      Define an allow list for features
  -h, --help                  Print help
  -V, --version               Print version

模板

模板是使用变量填充文件的 .html 文件。

如果提供了多个模板，则输出文件的名称将使用文件基本名称。这是为了避免每个模板生成一个新的 HTML 文件并覆盖以前的文件。
如果使用单个模板，则输出文件名将简单地是具有 .html 扩展名的 Markdown 文件，而不是 .md。

变量必须遵循以下规则

必须用 {{ 和 }} 括起来，两侧的空白字符是可选的。
必须以 £ 或 $ 字符开头。
必须以字母 a 到 z 开头，不区分大小写。
只能包含以下字符： a-z、0-9、_。

需要两个变量： title 和 content。
有关这些变量解析的更多内容，请参阅下面的章节。

有效模板页面的示例。

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="{{ £description }}">

    <title>{{ £title }}</title>
</head>
<body>
    <section>
        <h1>{{ £title }}</h1>
        <p>Authored by {{ £author }}</p>
    </section>
    <section>{{ £content }}</section>
</body>
</html>

首先，有一个用于 meta 描述标签的 £description 变量。
这将在每个 Markdown 文件的 meta 部分提供，包括 £author 变量。

此外，£title 变量在两个地方使用：文档标题和作为标题。
变量可以根据需要重复使用任意多次，只要它们遵循上述规则。

最后，£content 变量会根据 Markdown 文件的全部内容自动生成。

过滤器

可以通过提供过滤器来在渲染过程中修改占位符。
过滤器只是将预定义的函数应用于任何占位符变量的方式。

让我们使用之前的模板，并给 £title 变量应用一个简单的过滤器。

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="{{ £description }}">

    <title>{{ £title }}</title>
</head>
<body>
    <section>
        <h1>{{ £title | uppercase }}</h1>
        <p>Authored by {{ £author }}</p>
    </section>
    <section>{{ £content }}</section>
</body>
</html>

通过在管道字符（|）之后提供函数，我们可以在特定位置修改该变量。这在需要将占位符在模板中多次使用，但所有情况下的格式都应该不同时特别有用。

目前只支持这些过滤器；如果有可用参数，则包括它们的参数。
我们稍后讨论参数，但在此期间，要知道参数名称是可选的，只需要提供一个值。

lowercase - 将值转换为小写。
uppercase - 将值转换为大写。
markdown - 将值从 Markdown 转换为 HTML。
reverse - 反转字符串顺序。
truncate - 截断值为给定的长度，并在字符串被截断时添加尾随字符。
- characters - 默认值 - 限制字符串的字符数。
- trail - 如果字符串被截断，则添加到字符串末尾的字符。

默认情况下，除非在模板中指定，否则不会提供过滤器，但 £content 除外，它将应用 markdown。

过滤器不区分大小写，这意味着 | uppercase 与 | UPPERCASE 相同。它们也可以链接在一起，如下面的示例所示。

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="{{ £description }}">

    <title>{{ £title }}</title>
</head>
<body>
    <section>
        {{ £title | uppercase | markdown }}
        <p>Authored by {{ £author }}</p>
    </section>
    <section>{{ £content }}</section>
</body>
</html>

这里我们将标题转换为大写，然后将值转换为 markdown。
链式过滤器从左到右进行评估。

带有参数的过滤器

对于某些过滤器，可以提供可选参数。这是通过在等号（=）之后提供逗号分隔的列表来完成的。
每个过滤器都可以只提供名称，因为每个参数都已给定默认值。

这意味着这些全都相同。

<p>{{ £my_paragraph | truncate }}</p>
<p>{{ £my_paragraph | truncate = 20 }}</p>
<p>{{ £my_paragraph | truncate = trail: ... }}</p>
<p>{{ £my_paragraph | truncate = characters: 20, trail: ... }}</p>

正如您所看到的，您可以选择要覆盖的参数 - 如果有的话。

您也会注意到在第二个示例中我们没有提供键！
这是因为对于每个接受参数的过滤器，一个参数将被认为是“默认”参数。因此，如果您提供一个值，而没有参数名称，那么这将设置为该过滤器预定的默认参数。

Markdowns

Markdowns 是包含任何文本和可选 meta 部分的简单文本文件。

Markdown 文件的 meta 部分是此程序独有的。
本节必须位于文档顶部，并以 :meta 或 <meta> 开始，并以 :meta 或 </meta> 结束。
如果你使用 :meta 打开 meta 部分，则必须使用 :meta 关闭它；同样，对于 <meta> 和 </meta>，如果未正确关闭，则内容不会被读取。

使用 meta 部分提供已定义变量的模板值。因此，meta 部分中使用的变量必须遵循模板变量的规则。

如果Markdown中声明了变量但没有使用，将生成一个警告。
相反，如果模板没有为所有变量提供值，程序将停止执行。

不需要声明 meta 部分；但是，如果您不在内容顶部提供 <h1>（Markdown中的 # 同样可以接受）则需要一个标题变量。

以下是一个Markdown文件的示例，其中标题是从文档中解析出来的。

:meta
author = John Doe
description = This will appear in Search Engines.
:meta
# Markdown Title
This is the content of our file.

使用上述模板将生成以下输出。

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="This will appear in Search Engines.">

    <title>Markdown Title</title>
</head>
<body>
    <section>
        <h1>Markdown Title</h1>
        <p>Authored by John Doe</p>
    </section>
    <section>
        <h1>Markdown Title</h1>
        <p>This is the content of our file.</p>
    </section>
</body>
</html>

另一个示例，其中我们覆盖标题变量并使用前缀。

<meta>
£author = John Doe
£title = Meta Title
£description = This will appear in Search Engines.
</meta>
# Markdown Title
This is the content of our file.

这将生成以下输出

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="This will appear in Search Engines.">

    <title>Meta Title</title>
</head>
<body>
    <section>
        <h1>Meta Title</h1>
        <p>Authored by John Doe</p>
    </section>
    <section>
        <h1>Markdown Title</h1>
        <p>This is the content of our file.</p>
    </section>
</body>
</html>

为了方便，元值不需要用引号括起来，它们将解析到新行。但是，如果值中需要换行，则必须用双引号（"）括起来。
按照标准，引号需要转义，以防止字符串提前关闭；为此，只需在双引号前加上反斜杠，如下所示 \"。

:meta
header = Some Company
footer = "Copyright
John \"The Mystery\" Doe"
:meta

注释

可以通过在行首使用 # 或 // 来向 meta 部分添加注释。
注释将被解析，并且将删除开头的注释前缀，但是这并不必要，因为它们将在解析时被替换为 None，并随后被删除。

:meta
// This is a comment.
author = John Doe
# This is another type of comment
description = This will appear in Search Engines.
:meta

上述将要解析的元键值是 author 和 description，分别对应的值是 John Doe 和 This will appear in Search Engines.。

输出

所有HTML文件都将生成与它们转换的Markdown文件相同的名称，但带有模板的扩展名。

默认情况下，文件将在Markdown文件相同的目录中创建，但是，通过提供 --output-dir（如果更容易，则可以使用 -o）可以更改输出目录。
这不会重命名文件，而只是将其放置在指定的目录中。

生成的输出将应用一些格式，但如果你想要文档正确格式化，可能需要人工干预，例如缩进。
目前，所有标题（从 h2 到 h6）之前都添加了新行，但其他内容没有变化。

允许列表

在某些情况下，此程序会报告警告。

这些警告不会阻止程序运行，但会将警告信息打印到控制台。
例如，未使用的变量。

考虑如果我们有一个Markdown文件，它声明了键值对 author = John Doe，然后在模板中从未引用该变量，那么通常模板仍然会创建，但控制台会有如下警告。

Warning: Unused variable in 'path/to/file.md': author

如果您不希望打印此消息，可以使用以下命令。

blogs-md-easy -m path/to/file.md -t path/to/template.html --allow unused
blogs-md-easy -m path/to/file.md -t path/to/template.html --allow unused_variables

依赖项

~4MB
~82K SLoC