mdbook-template
A mdbook preprocessor that allows the re-usability of template files with dynamic arguments
Table of Contents
- Author Notes
- Installation
- About
- Format
- Valid Configurations
- Example
- GitHub Actions
- License
- Contributing
- Acknowledgement
Author Notes
I'm still a beginner in terms of my Rust skills, so I'm definitely... probably sure that there are edge cases within this preprocessor.
Installation
Install Through Cargo
$ cargo install mdbook-template
Add the following line into your book.toml
[preprocessor.template]
You're good to go :D
Continue building your mdbook normally!
$ mdbook build
About
Given the following directory structure
book.toml
src
├── rust.md
├── go.md
├── friends
│ └── hazel.md
├── images
│ ├── ferris.png
│ └── corro.png
└── SUMMARY.md
If we wanted to include the images ferris.png and corro.png within all the files through a footer, we'd have to copy the same piece of markdown/code in every file and set a unique path back to the images/ directory.
This is where mdbook-template can help with the introduction of {{#template ...}.
Being based on the {{#include ... }} feature of mdbook, mdbook-template allows you to use familiar syntax to include files while passing in arguments to allow for dynamic generation of text.
Please view the given example which demonstrates it in action.
Format
Template
The format is as follows
1 2 3
{{#template <file> <args>}}
- The identifier that tells
mdbook-templatethat this text should be replaced by a template - The
relative pathto the template file - Any arguments that should be substituted within the template file. Arguments should be seperated by whitespace and should be in the
key=valueformat.
Arguments
Arguments to be replaced within the template files should be wrapped in [[# ...]]
The format is as follows
1
[[#<name>]]
- The name of the argument
Default Values
Default values can be set in case some files need dynamic arguments and other don't.
The format is as follows
1 2
[[#<name> <default-value>]]
- The name of the argument
- The value that this argument should have by default
Valid Configurations
Template Config
{{#template file.txt path=../images author=Goudham}}
{{#template
file.txt
path=../images
author=Goudham
}}
// Not recommended but valid
{{#template file.txt path=../images author=Goudham}}
// Not recommended but valid
{{#template
file.txt
path=../images
author=Goudham
}}
Arguments Config
\[[#escaped]]
[[#width]]
[[#width 200px]]
// Not recommended but valid
[[ #width 400px ]]
Example
Given the following directory
book.toml
src
├── rust.md
├── go.md
├── friends
│ └── hazel.md
├── images
│ ├── ferris.png
│ └── corro.png
├── templates
│ └── footer.md
└── SUMMARY.md
and the following content
templates/footer.md
-- Designed By [[#authors]] --
rust.md
# Rust
Some Content...
{{#template templates/footer.md authors=Goudham, Hazel path=images}}
go.md
# Go
Some Content...
{{#template templates/footer.md path=images authors=Goudham, Hazel}}
friends/hazel.md
# Hazel
Some Content...
{{#template ../templates/footer.md path=../images authors=Goudham, Hazel }}
After running mdbook build with the mdbook-template preprocessor enabled, the files will have dynamic paths to the images and contain identical content.
rust.md
# Rust
Some Content...
-- Designed By Goudham, Hazel --
go.md
# Go
Some Content...
-- Designed By Goudham, Hazel --
friends/hazel.md
# Hazel
Some Content...
-- Designed By Goudham, Hazel --
Further examples are included within the examples directory which demonstrate a variety of usages.
GitHub Actions
Include the following within your .yml workflow files if you need mdbook-template as an executable to build your book.
- name: Install mdbook-template
run: |
mkdir mdbook-template
curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template
echo `pwd`/mdbook-template >> $GITHUB_PATH
The above step will ensure the latest version of mdbook-template is retrieved and built.
License
Contributing
First, thanks for your interest in contributing to this project! Please read the CONTRIBUTING.md before contributing!
Acknowledgement
This preprocessor is heavily based off the links.rs file within mdbook itself. I definitely wouldn't have been able to mock up something like this without the strong foundations that mdbook already implemented.
![[TEM #2] - Enable Default Values To Be Set](https://avatars.githubusercontent.com/u/58985301?v=4)
62 Dec 5, 2022
10 Jun 16, 2022
13 Jun 26, 2023
33 Sep 25, 2022
3.2k Jan 4, 2023
1 May 2, 2022
6 Oct 31, 2022
94 Jan 26, 2023
3 Nov 8, 2023
18 Jun 18, 2022
2 Feb 11, 2022
6 Jan 30, 2022
16 Sep 18, 2022
1 Dec 28, 2021
209 Dec 24, 2022
17 Jul 31, 2022
1 Jan 8, 2022
17 Jul 31, 2022
1 Mar 7, 2022