Tired of copy-pasting your example configurations or bumping hardcoded versions in your README?
mdtmpl
is a dead-simple little Go CLI tool that runs instructions defined in Markdown comments (e.g: <!--- {{ my markdown comment }} --->
).
mdtmpl
ships with the default Go-Template functions,sprig and some useful functions for building README files such as:
{{ code "<highlighting>" "<content>" }}
: which will wrap the given content in a code block using the specified syntax highlighting{{ exec "<command>" }}
: executes the given command and returns its output{{ tmpl "<template-file>" }}
: to include and render another template file{{ tmplWithVars "<template-file>" "<key>=<value>" "<key>=<value>"}}
: to include and render another template file with additional vars in the form of<key>=<value>
{{ conventionalCommitBump }}
: will result to the next semantic version according to the latest git commit message.
You can also pipe the output of one instruction to the next one as its last parameter:
<!--- {{ "hello!" | upper | repeat 5 }} --->
translates to HELLO!HELLO!HELLO!HELLO!HELLO!
You can find a comprehensive example here and its README.md.tmpl
Even this README.md
is generated using mdtmpl
!
Imagine the following README.md.tmpl
that contains a Markdown comment {{ file "config.yml" | code "yml" }}
, telling mdtmpl
to include the content of config.yml
and wrap it in a code block (```
) using YAML
syntax highlighting:
### Example Configuration
Here are all available configuration options:
<!--- {{ file "config.yml" | code "yml" }} --->
### Start
You can start the installation by running `make start`
<!--- {{ exec "make start" | code "bash" }} --->
when running mdtmpl -t README.md.tmpl
it will write the following output to the README.md
:
Here are all available configuration options:
cfg:
setting: true
install: false
You can start the installation by running make start
[...]
Find all releases here or simply download the latest by running:
## curl
version=$(curl https://api.github.com/repos/falcosuessgott/mdtmpl/releases/latest -s | jq .name -r)
curl -OL "https://github.com/FalcoSuessgott/mdtmpl/releases/download/${version}/mdtmpl_$(uname)_$(uname -m).tar.gz"
tar xzf mdtmpl_$(uname)_$(uname -m).tar.gz
chmod u+x mdtmpl
./mdtmpl version
## brew
brew install falcosuessgott/tap/mdtmpl
$> mdtmpl -h
template Markdown files using Go templates and Markdown comments
Usage:
mdtmpl [flags]
Flags:
-d, --dry-run dry run, print output to stdout (env: MDTMPL_DRY_RUN)
-f, --force overwrite output file (env: MDTMPL_FORCE)
-h, --help help for mdtmpl
-o, --output string path to the output file (env: MDTMPL_OUTPUT_FILE) (default "README.md")
-t, --template string path to a mdtmpl template file (env: MDTMPL_TEMPLATE_FILE) (default "README.md.tmpl")
--version print version (env: MDTMPL_VERSION)
Add the following config to your .pre-commit-config.yaml
file and adjust the args
to your needs.
Mae sure to run pre-commit install
and pre-commit autoupdate
to stay on the last version:
repos:
- repo: https://github.com/FalcoSuessgott/mdtmpl
rev: v0.1.0
hooks:
- id: mdtmpl
args: [-t=README.md.tmpl, -f, -o=README.md]