From 4c5c4c9711f10a0f09fcf34f1d3720bfaa9c5ede Mon Sep 17 00:00:00 2001
From: Scott Sanderson <scott.b.sanderson90@gmail.com>
Date: Sat, 2 Nov 2024 15:27:37 -0400
Subject: [PATCH] DOC: Add basic docs.

---
 README.md              | 69 ++++++++++++++++++++++++++++++++++++++++++
 example-book/README.md |  3 ++
 example-book/book.toml | 17 +++++++++++
 3 files changed, 89 insertions(+)
 create mode 100644 README.md
 create mode 100644 example-book/README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4cdabb5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,69 @@
+# mdbook-minijinja
+
+mdbook-minijinja is an [mdbook][mdbook] [preprocessor][mdbook-preprocessor]
+that evaluates the files in your book as [minijinja][minijinja]
+templates. Template features are fully supported inside book chapters.  Limited
+template features are available in `SUMMARY.md` (see below).
+
+[mdbook]: https://rust-lang.github.io/mdBook
+[mdbook-preprocessor]: https://rust-lang.github.io/mdBook/format/configuration/preprocessors.html
+[minijinja]: https://docs.rs/minijinja/latest/minijinja/
+
+## Example Configuration
+
+```toml
+# book.toml
+[preprocessor.minijinja]
+
+# Configure behavior of evaluating undefined variables in minijinja.
+#
+# Options are "strict", "lenient", or "chained".
+#
+# See https://docs.rs/minijinja/latest/minijinja/enum.UndefinedBehavior.html
+# for more details.
+#
+# Default value is "strict".
+undefined_behavior = "strict"
+
+# Path to a directory containing minijinja templates. Minijinja import and
+# include directives will look for templates here.
+#
+# If this path is absolute, it is used as-is. If it is relative, it is
+# interpreted relative to the path containing book.toml.
+#
+# See https://docs.rs/minijinja/latest/minijinja/fn.path_loader.html for more
+# details.
+#
+# Default value is "templates".
+templates = "templates"
+
+# Variables defined in this section will be available for use in templates.
+[preprocessor.minijinja.variables]
+my_var = "my_var_value"
+chapter_1_name = "Cool Chapter 1"
+part_1_name = "Cool Part 1"
+part_2_name = "Cool Part 2"
+condition_true = true
+condition_false = false
+list_of_strings = ["foo", "bar", "buzz"]
+partial_chapter_name = "Partial"
+```
+
+## SUMMARY.md Limitations
+
+The structure of an mdbook is defined by the top-level
+[SUMMARY.md](https://rust-lang.github.io/mdBook/format/summary.html) file,
+which contains a list of the book's chapters and titles. mdbook only invokes
+preprocessors after it has already parsed and evaluated SUMMARY.md. This means
+mdbook-minijinja can only support a limited set of jinja template operations in
+SUMMARY.md:
+
+- ✅ Simple if/else conditionals to enable or disable chapters based on
+  variables are supported.
+- ✅ Template expressions within chapter and part titles are supported.
+- ❌ `{% include %}` or other template expansions that evaluate to new book
+  chapters are not supported. All book chapters must be present in the
+  SUMMARY.md source.
+
+For an example of supported functionality, see the [example
+book](./example-book/src/SUMMARY.md).
diff --git a/example-book/README.md b/example-book/README.md
new file mode 100644
index 0000000..62b3187
--- /dev/null
+++ b/example-book/README.md
@@ -0,0 +1,3 @@
+# Example mdbook-minijinja Configuration
+
+This directory contains an example mdbook-minijinja configuration.
diff --git a/example-book/book.toml b/example-book/book.toml
index 233bf97..e0465aa 100644
--- a/example-book/book.toml
+++ b/example-book/book.toml
@@ -6,9 +6,26 @@ src = "src"
 title = "MDBook Minijinja Example"
 
 [preprocessor.minijinja]
+
+# Configure behavior of evaluating undefined variables in minijinja.
+#
+# Options are "strict", "lenient", or "chained". Default is "strict".
+#
+# See https://docs.rs/minijinja/latest/minijinja/enum.UndefinedBehavior.html
+# for more details.
 undefined_behavior = "strict"
+
+# Path to a directory containing minijinja templates. Minijinja import and
+# include directives will look for templates here.
+#
+# If this path is absolute, it is used as-is. If it is relative, it is
+# interpreted relative to the path containing book.toml.
+#
+# See https://docs.rs/minijinja/latest/minijinja/fn.path_loader.html for more
+# details
 templates = "templates"
 
+# Variables defined in this section will be available for use in templates.
 [preprocessor.minijinja.variables]
 my_var = "my_var_value"
 chapter_1_name = "Cool Chapter 1"