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模板引擎

Download history 254/week @ 2024-08-03 163/week @ 2024-08-10 159/week @ 2024-08-17

576 每月下载量

MIT 许可证

1MB
1.5K SLoC

journing robot

🗒️ 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,并定义了三个数据点:titlecategorypriority。这确保了每个创建的记录都将收集这三个后续数据点。

一旦设置了一个主题,就可以为它创建一个 "条目"。以下是一个创建决策记录的示例命令

Panic for Pleasure

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