Reusing Contents

Variables

MarkBind does not aim to alter the already robust variable features of Nunjucks, but provides several extensions to it.

Global Variables

Global variables are to be defined in the _markbind/variables.md file. Each variable must have an name and the value can be any MarkBind-compliant code fragment. The name should not contain - and .. For example, search-option and search.options are not allowed.

The variables declared here are available from anywhere in the code base.

<variable name="year">2018</variable>

<variable name="options">
* yes
* no
* maybe
</variable>

    

      


    
    
    

    


    
    

To include a variable value in your code, give the variable id enclosed in Nunjucks' double curly braces syntax.

Built-in Global Variables

MarkBind also provides a number of built-in variables.

Importing variables from other external file formats

You can also source variables from external files using MarkBind's {% ext varName = "filepathToFile" %} Nunjucks extension. This is useful if you have external datasets you want to display in your site!

To do so, assign a root variable name (varName) to the file path from the . You may then access the file's variables using dot varName.xx or array varName[i] syntax, depending on the file's contents.

{% ext studentScoreboard = "userGuide/syntax/extra/scoreboard.json" %}

Student Number | Score | Rank
:----- | :-------: | ----
{% for student in studentScoreboard.students -%}
{{ student.number }} | {{ student.score }} | {{ student.rank }}
{% endfor %}

<small>Last updated at {{ studentScoreboard.lastUpdated }}</small>

    

      


    
    
    

    


    
    

{% ext studentScoreboard = "userGuide/syntax/extra/scoreboard.csv" %}

Student Number | Score | Rank
:----- | :-------: | ----
{% for student in studentScoreboard -%}
{{ student.number }} | {{ student.score }} | {{ student.rank }}
{% endfor %}

    

      


    
    
    

    


    
    

Place global variables in `_markbind/variables.md`
<variable name="year">2018</variable>
The year was {{ year }}

    

      


    
    
    

    


    
    

Includes

You can use <include> tag to include another markdown or HTML document into the current document.

Tip 1. ...
<include src="tips/tip2.md" />
Tip 3. ...

    

      


    
    
    

    


    
    

You can <include> a fragment of a file by specifying the #fragment-id at the end of the src attribute value, provided the fragment is wrapped in a <div>/<span> tag with the matching id.

Some text
<include src="docs/tips.md#tip-1" />
Some other text

    

      


    
    
    

    


    
    

...
<div id="tip-1" />
  Tip 1. ...
  ...
</div>
Tip 2. ...

    

      


    
    
    

    


    
    

Attributes:

• src: specify the source file path.
• inline (optional): make the included result an inline element. (wrapped in <span> tag). e.g.,

  The title is <include src="../docs/summary.md#title" inline /> while ...
  
      
  
        
  
  
      
      
      
  
      
  
  
      
      

• optional (optional): include the file/fragment only if it exists i.e., there will be no error message if the file/fragment does not exist. e.g.,

  <include src="UserStories.md" optional />
  
      
  
        
  
  
      
      
      
  
      
  
  
      
      

• trim (optional): remove leading and trailing whitespace and newlines from the document before including.

  <include src="UserStories.md#epic" trim />
  
      
  
        
  
  
      
      
      
  
      
  
  
      
      

• omitFrontmatter (optional): omit the frontmatter of the file/fragment from being included (if any).

  <include src="UserStories.md#epic" omitFrontmatter />
  
      
  
        
  
  
      
      
      
  
      
  
  
      
      

<include> Inside an Included File

Although the src attribute of an <include> is given relative to the current directory, it is converted to an absolute value before the is included from another file.

# My Book
<include src="chapter1.md" />
<include src="chapter2.md" />

    

      


    
    
    

    


    
    

# My Review
<include src="../bookFiles/book.md" />
...

    

      


    
    
    

    


    
    

In other words, <include> interprets the reused code relative to the original location of the file, not the location in which it is reused.

Specifying Variables in an <include>

It is possible to include variables in an <include>.

<include src="article.md">
  <variable name="title">My Title</variable>
  <variable name="author">John Doe</variable>
</include>

    

      


    
    
    

    


    
    

# {{ title }}<br>
Author: {{ author }}

    

      


    
    
    

    


    
    

These variables work the same way as variables in _markbind/variables.md, except that they only apply to the included file. They allow the included file to be reused as a template, for different source files using different variable values.

You can also specify include variables within the <include> tag itself by adding a var- prefix.

<include src="article.md" var-title="My Title" var-author="John Doe" />

    

      


    
    
    

    


    
    

If the same variable is defined in a chain of <include>s (e.g. a.md includes b.md includes c.md...), variables defined in the top-most <include> will take precedence. Global variables (_markbind/variables.md) will take precedence over any <include> variables. This is to allow the outer context to adapt the reused content without changing its actual content.

Excluding Files from Rendering as Pages

MarkBind supports the exclusion of files from page generation. For example, you can exclude files containing that are only meant to be used in <include>.

{
  "pages": [
    {
      "glob": "*.md",
      "layout": "normal",
      "searchable": "yes"
    }
  ],
}

    

      


    
    
    

    


    
    

Example Suppose you have a fragment file content-fragment.md and you want to include it in some pages of the site course without rendering content-fragment.md as a page.

In reading.md (note how it reuses content from the content-fragment.md):

# Week 1 Reading:
<include src="content-fragment.md" />

    

      


    
    
    

    


    
    

In site.json we then exclude the fragment from the page generation with pagesExclude:

...
"pagesExclude": [
  "**/*-fragment.md"
],
...

    

      


    
    
    

    


    
    

Using Boilerplate Files

If you find yourself duplicating a fragment in multiple places of your code base, you can use a boilerplate file to avoid such duplication. Note that you cannot use a normal <include> in this case because the code included using a normal <include> stays relative to the original location while boilerplate code needs to be interpreted relative to the location it is being used.

# My Book
<include src="chapter1/chapter.md" />
<include src="chapter2/chapter.md" />

    

      


    
    
    

    


    
    

## Text
<include src="text.md" />
## Exercises
<include src="exercises.md" />

    

      


    
    
    

    


    
    

## Text
<include src="text.md" />
## Exercises
<include src="exercises.md" />

    

      


    
    
    

    


    
    

To use a code fragment as a boilerplate file,

1. Put the code in a file inside the _markbind/boilerplates directory.
2. <include> the file as if a copy of it exists in any directory you want it to applied, but add the boilerplate attribute to the <include> tag.

# My Book
<include src="chapter1/chapter.md" boilerplate />
<include src="chapter2/chapter.md" boilerplate />

    

      


    
    
    

    


    
    

## Text
<include src="text.md" />
## Exercises
<include src="exercises.md" />

    

      


    
    
    

    


    
    

If you have many boilerplate files, you can organize them into directories inside the _markbind directory. When using such boilerplate files, you need to replace boilerplate attribute with boilerplate="<path to file relative to _markbind/boilerplates>".

<include src="chapter1/chapter.md" boilerplate="book/chapter.md" />
<include src="chapter2/chapter.md" boilerplate="book/chapter.md" />

    

      


    
    
    

    


    
    

<include src="foo.md#bar" boilerplate inline trim>
  <variable name="x">5</variable>
</include>