Cat-Prep - mdBook 预处理工具，用于创建学习材料库

此预处理工具允许在 mdBook 书籍中生成教师、科目、材料和标签的层次结构。

尽管与 html 渲染器配合得最好，但没有对后端的限制。目前 LaTeX 和 EPUB 后端的输出不太令人满意，但错误在于渲染器

• 没有完全支持 markdown 和 HTML。

cat-prep 因此是面向未来的，并且随着这些渲染器的改进，其输出格式也将得到改进。

需求

• 任意 Linux
• 以下程序
  • ls
  • xargs
  • git
  • sh
  • true
  • mdbook 及其 links 预处理程序（必须在 book.toml 中在 cat-prep 之前指定）
• 为了使 cat-prep 能够工作，mdbook 必须在 git 仓库内运行

文档

可以通过以下方式访问 API 文档：

• cargo doc --no-deps --open (--no-deps 用于跳过依赖项，以加快文档编译速度)i
• https://docs.rs/mdbook-cat-prep/

大多数符号都有简短和详细的文档，因此建议展开它们。

安装

最简单的安装方法是使用 cargo 工具安装。

安装最新发布的版本

cargo install mdbook-cat-prep

从 git 安装最新版本

cargo install --git "https://github.com/gjk-cat/cat-prep"

还可以在克隆的仓库内进行手动安装

git clone https://github.com/gjk-cat/cat-prep
cd cat-prep
cargo install --path .

注意：以调试模式安装允许查看 CatContext。

使用

使用 cat-prepu 的前提是满足上述要求，并且程序 mdbook-cat-prep 存在于 PATH 中，无论通过安装还是其他方式。

0. 首先需要在 mdbook 中设置使用预处理器 cat-prep

# v souboru book.toml na konec
[preprocessor.cat-prep]

其他推荐设置

[output.html]
theme = "src/theme" # kde src/theme vede k naklonovanému kočičkovému tématu.
# pro jeho správnou funkcí je zapotřebí kočičkový obrázek, který je k nalezení
# ve většině repozitářů. Popř. jde nahradit libovolným jiným obrázkem.
# Zvířátka preferována

1. 然后需要创建 teachers 文件夹，并尽可能为您的账户创建第一个教师。

mkdir teachers
kak teachers/jmeno.toml # zvolte libovolný editor

在 jmeno.toml 文件中

jmeno = "Lukáš Hozda"         # má odpovídat jménu, které osoba používá v gitu, tj. `user.name`
email = "[email protected]" # odpovídá email, který osoba používá v gitu, tj. `user.email`
username = "magnusi"          # pro kontexty, kde se nevyplatí používat email nebo jméno, např. odkazy
# libovolný popisek, formátován jako markdown, může sloužit na extra informace
# doporučuje se začínat na třetí úrovni nadpisů v zájmu přehlednosti seznamu vyučujících
bio = """
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Sed lacinia hendrerit placerat.

### Mauris posuere libero dui
non feugiat nunc imperdiet non. Ut pharetra sodales mi,
quis __sagittis__ velit __tristique__ tincidunt.[1]

### Sed in tellus tincidunt, molestie libero vel,
semper mi. Praesent lacus felis, `aliquam` in tempor vel,
fringilla eget dui. Quisque *tristique* pulvinar fringilla.

[1]: <https://www.lipsum.com/feed/html>
"""

2. 之后可以创建任意页面，这些页面不属于任何科目，请参阅 https://rust-lang.github.io/mdBook/。

3. 创建第一个项目。项目的位置可以是任意的，只要满足以下三个条件：

   1. 位于 src 文件夹的子文件夹中（理论上，在 src 中也可以工作，但那样可能只能有一个项目）
   2. 不在其他项目的子文件夹中
   3. 包含 subject.md 文件的文件夹

mkdir -p src/predmety/predmet1
touch src/predmety/predmet1/subject.md
kak src/predmety/predmet1/subject.md # nebo libovolný jiný editor

接下来，在 subject.md 文件中创建标题和一些初始内容。

nazev = "Můj první předmět"
zodpovedna_osoba = "Lukáš Hozda"
# ↑ pokud možno, mělo by odpovídat jménu, emailu nebo usernamu některého vyučujícícho
#   pokud je autorem někdo jiný, zadejte email.
bio = "krátký popisek předmětu"

+++

## Můj první předmět

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
In varius lacinia risus eu vehicula. Vestibulum consectetur
feugiat dignissim. Mauris sed leo id lectus commodo egestas.
Integer sed ligula quis lorem viverra fringilla lobortis at elit.
Fusce a eros laoreet, dictum enim et, pellentesque erat.

文件末尾不应有任何可能破坏项目材料打印的内容。

4. 然后可以创建该项目的第一个材料

touch src/predmety/predmet1/material1.md
kak src/predmety/predmet1/material1.md # nebo libovolný editor

接下来需要在 material.md 文件中创建标题和初始内容。

nazev = "Můj první článek"
tagy = ["tag1", "tag2", "tag3"]
datum = "20.1.2019"  # dobrovolné a libovolné. Jelikož "datum" je singulár  od "data", lze použít jakkoliv :^)

+++

# Můj první článek

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
In varius lacinia risus eu vehicula. Vestibulum consectetur
feugiat dignissim. Mauris sed leo id lectus commodo egestas.
Integer sed ligula quis lorem viverra fringilla lobortis at elit.
Fusce a eros laoreet, dictum enim et, pellentesque erat.

5. 现在不要忘记在 SUMMARY.md 中提及这些文件（参见 mdbook 的说明），否则 mdbook 以及 cat-prep 都将无法看到。猫科动物的层次结构与 SUMMARY.md 的并行层次结构平行，但反映猫科动物的层次结构在猫科动物的层次结构中也不是什么坏事。

...

- [Předmět 1](./predmety/predmet1/subject.md)
	- [Článek 1](./predmety/predmet1/material1.md)

...

6. 现在可以组装书籍

mdbook build

或者启动书籍开发的 live-reload 服务器

mdbook serve

模板

或者可以使用来自 https://github.com/gjk-cat/sablona 存储库的模板

自动部署到 ZEIT.CO

gjk.cat 可以相当简单地在 ZEIT.CO 平台上部署。

0. 在 ZEIT.co 上建立账户后，启用与 Github 或 Gitlab 的集成
1. 将猫科动物的实例作为项目导入 ZEIT
2. 在安装过程中，将 sh ./build 作为构建命令，并将输出文件夹作为 book。其他值无需更改
3. 这应该会在添加新提交后设置自动部署。现在将 build.def 文件从 cat-prepu 复制到存储库中
4. 根据文件中的值替换值，并将其重命名为 build
5. 推送后，项目应该会正确部署

注意。由于目前 ZEIT 无法保留 .git 文件夹，所以在脚本中有一个命令会重新克隆存储库并在此处编译书籍。因为 cat-prep 为了其功能需要在 git 存储库中工作并读取其历史。

许可证

该文件由 Fair 开源许可证授权

Lukáš Hozda <me@magnusi.tech> 2020 (c)

Usage of the works is permitted provided that this instrument is retained with the works, so that any entity that uses the works is notified of this instrument.

DISCLAIMER: THE WORKS ARE WITHOUT WARRANTY.