Skip to content

Templating

A basic mdtmpl instruction looks like this:

<!--- {{ <template-function> <arg01> <args02> ... }} --->

mdtmpl parses the template file and all its markdown comments and renders its instructions. It uses the Go`s Template Engine.

Follow this document to see which template functions are supported.

Piping

You can pipe the output of one instruction to the next template function as its last argument:

<!--- {{ <template-function> <arg01> <args02> | <template-function> <args> ... }} --->

For example: <!--- {{ "hello!" | upper | repeat 5 }} ---> will result in: HELLO!HELLO!HELLO!HELLO!HELLO!.

Template Functions

mdtmpl includes all sprout and Go`s predefined template functions.

Furthermore, the following functions are also available:

code "<language>" "<content>"

Syntax highlight a given content in a specified language within a code block.

<!--- {{ echo "this is a command" | code "bash" }} --->


this is a command

exec "<command>"

Executes a given command and returns the output and an error (if any)

Tip

truncate removes any trailing empty lines. Useful after exec

<!--- {{ exec "echo hello world" | truncate | code "bash" }} --->


hello world

hook "<command>"

Executes a given command and returns an error (if any)

Tip

hook is useful for setting things up or commands that produce some resources, such as images that you want to include.

<!--- {{ hook "docker start vault" }} --->

file "<path>"

Includes the content of the given file

# settings.yml
settings:
    basic_auth: false

<!--- {{ file "settings.yml" | code "yaml" }} --->


settings:
    basic_auth: false

fileHTTP "<url>"

Includes the content of the given url

# settings.yml
settings:
    basic_auth: false

<!--- {{ fileHTTP "https://github.com/settings.yml" | code "yaml" }} --->


settings:
    basic_auth: false

filesInDir "<dir>" "<glob-pattern">

Returns the paths of all matching files in the specified directory

<!--- {{ filesInDir "." "*.yml" }} --->

[.github/dependabot.yml .github/workflows/lint.yml .github/workflows/mkdocs.yml .github/workflows/release.yml .github/workflows/test.yml .golang-ci.yml .goreleaser.yml cmd/testdata/cfg.yml mkdocs.yml pkg/template/testdata/values.yml]

tmpl "<template-file>"

Includes the rendered content of the given template

# docs/template.tmpl
This is a test {{ exec "echo template" }}

<!--- {{ tmpl "docs/template.tmpl" }} --->

This is a test template

tmplWithVars "<template-file>" <values>

Renders a given template with the specified template values

# values.yml
name: kubernetes
version: v1.0.0

# docs/template.tmpl
This is another template {{ .name }}-{{ .version }}

<!--- {{ tmplWithVars "docs/template.tmpl" (file "values.yml" | fromYAML) }} --->

This is another template kubernetes-v1.0.0

stripansi "<content>"

Strips any Color Codes from a given content

Tip

Useful when a command outputs colored output

<!--- {{ exec "docker ps" | stripansi | code "bash" }} --->


CONTAINER ID   IMAGE        COMMAND                  CREATED       STATUS          PORTS                                       NAMES
cf4f9cec8faa   registry:2   "/entrypoint.sh /etc…"   7 weeks ago   Up 29 minutes   0.0.0.0:5000->5000/tcp, :::5000->5000/tcp   registry

collapsile "summary" "<content>"

Creates a collapsible section wit the given summary and content.

<!--- {{ collapsile "output" (exec "make" | stripansi | truncate | code "bash" ) }} --->

output

fmt                            format go files
help                           list makefile targets
lint                           lint go files
test                           display test coverage

toc

Inserts a Markdown Table of Content

Note

For now it does not work for any headings that are included after toc function invocation. For example when using file or tmpl/tmplWithVars

# ToC
<!--- {{ toc }} --->
# 1. Heading
## 2. Heading
### 3. Heading
## 4. Heading

# ToC
- [ToC](#toc)
- [1. Heading](#1.-heading)
- [2. Heading](#2.-heading)
    - [3. Heading](#3.-heading)
- [4. Heading](#4.-heading)

# 1. Heading
## 2. Heading
### 3. Heading
## 4. Heading