4 个版本
0.2.3 | 2024 年 8 月 17 日 |
---|---|
0.2.2 | 2024 年 8 月 16 日 |
0.2.1 | 2024 年 8 月 7 日 |
0.2.0 | 2024 年 8 月 3 日 |
#56 在 模板引擎
576 每月下载量
1MB
1.5K SLoC
🗒️ mdBook Journal
一个工作流程工具,允许您生成模板化的文档、笔记、测量...或任何东西。其核心是日志 "主题" 的概念。您指定每个主题跟踪的核心数据,然后开始工作!
注意:这是为 mdBook
文档系统设计的插件项目。它并不复杂;然而,您需要了解它的工作原理,以便利用此工具的一些功能。
🔩 示例演示
假设您想记录团队做出的每个重要的 架构决策
。
您可以在 book.toml
中定义此类主题
# Example "book.toml" that demonstrates how to setup
# setup a simple Architectural Decision Record
#
[book]
authors = ["Crazy Dev"]
language = "en"
multilingual = false
src = "src"
title = "roflcopterz"
# You'll need `mdbook-journal` in your path
# make sure the following command works:
#
# `mdbook-journal -V`
#
[preprocessor.journal]
command = "mdbook-journal"
# Setting Up A Journal Topic
#
# This is how you would create a topic of "ADR".
#
# The key immediately after `topics` is the name
# of the topic. --------------+
# |
[preprocessor.journal.topics.ADR]
# The `path_mapping` drives the strategy for generating
# the path location of each entry. It supports a mixture
# of handlebars for any topic data and also is formatted
# against the `CREATED_AT` time.
#
# In this example the directory structure will be the
# year of the title as the root directory, followed by
# a directory for the category, and then lastly the title
# as the filename. It should be pointed out that a `.md`
# extension is automatically appended to the path.
#
# Date Interpolation Docs:
# <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>
#
# default = "%Y/%B/%d-%H-%M-%S-{{kebabCase title}}"
#
path_mapping = "%Y/{{kebabCase category}}/{{kebabCase title}}"
# Entry Template
#
# String template value that is used when generating
# a new "Entry" for this topic. This template is
# interpolated with the data provided from the required
# variables.
#
# default = ""
#
template = """
## Category: **{{category}}**
## ADR: **{{titleCase title}}**
### Problem Statement
What are we solving for?
"""
# This is how you specify a topic's meta data.
#
# Each key maps to the front-matter which is pinned
# to all journal entries. Currently `title` is
# required to generate file names. Feel free to add
# as many more fields that you want.
#
# Field Options
#
# - required = false
#
# If a field is required this means it's creation
# and updates must have a valid representation of
# the data. Presently that just means it cannot
# be empty.
#
# - default = ""
#
# Value to provide if the field has failed the
# validation phase. It should be noted that a
# default is also provided even if the field is
# not required. ** This is likely to change **
#
# This is the topic name ---+
# |
[preprocessor.journal.topics.ADR.variables]
title = { required = true }
category = { required = true }
priority = { required = true, default = "low" }
在此示例中,主题名称为 ADR
,并定义了三个数据点:title
、category
和 priority
。这确保了每个创建的记录都将收集这三个后续数据点。
一旦设置了一个主题,就可以为它创建一个 "条目"。以下是一个创建决策记录的示例命令
markdown-journal new ADR
这将生成一个提示,收集这些数据点
(category)❯ rust
(priority)❯ high
(title)❯ panic for pleasure
假设输入了上述内容,它将在您的项目中生成以下文件
src/ADR/2024/rust/panic-for-pleasure.md
---
CREATED_AT: 2024-07-25T00:46:13.541231172+00:00
TOPIC: ADR
category: rust
priority: high
title: panic for pleasure
---
## Category: **rust**
## ADR: **Panic For Pleasure**
### Problem Statement
What are we solving for?
这是 markdown 规范的顶部部分,称为 front matter
。它允许分配特定数据,并且是日志操作的前沿。通过这种方式添加的所有条目都自动包含在生成的 HTML 文档中,而无需在 SUMMARY.md
文件中包含它们。
⚙️ 本地安装
目前,要安装您需要克隆此仓库并使用 cargo 进行安装
git clone https://github.com/benfalk/mdbook-journal.git
cargo install --path mdbook-journal
验证是否正确安装
mdbook-journal -V
mdbook-journal0.2.0
依赖项
~17–32MB
~481K SLoC