# docsify-mustache

> Preprocessing markdown documents with Mustache

- On the fly preprocessing documents
- Mustache variables in markdown
- Variables from JSON and XML
- Variables from front matter

Get Started GitHub

# docsify-mustache

Version 1.0.5

A Docsify plugin that allow preprocessing markdown documents with Mustache template engine. You can substitute variables in markdown documents using mustache syntax `{{variable}}` and `{{variable.property}}` . Variables can be load from various sources, including front matter section of markdown documents, external JSON or XML files and Docsify configuration.

## Installation

Add following script tag to your `index.html` after docsify.

    <script src="//cdn.jsdelivr.net/npm/docsify-mustache"></script>

Optionally add docsify-front-matter plugin to access markdown front matter variables.

    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/front-matter.min.js"></script>

## Options

### data

You can load Mustache variables with `data` option. The value can be a string , object or array .

- string value interpreted as data file URL (relative or absolute). Both JSON and XML data file formats are supported.

  - properties from JSON data file will be available as Mustache variables
  - XML root element will be mapped to Mustache variable with root elements tag name as variable name

- object properties will be mapped to Mustache variables using property name as variable name

- array may be use to specify multiple string or object values as data sources

  Example:

    window.$docsify = {
      mustache: {
        data: [
          'doc/vars.json',
          'doc/pom.xml',
          {
            question: 'What is your favorite number?'
          }
        ]
      }
    }

Note

There is no way to access XML attributes, tag names used for hierarchy and for referring element’s inner text.

### package

The plugin loads `package.json` and make it available for Mustache as `package` variable. You can disable this feature setting `noPackage` option to `true` value:

    window.$docsify = {
      mustache: {
        noPackage : true
      }
    }

## Sources

### Front Matter

If docsify-front-matter plugin loaded and actual markdown file has front matter data then the front matter keys will be mapped to Mustache variables with same name. The front matter data has the highest priority if variables exists with same name in multiple data sources.

Example:

    ---
    answer: 42
    question: What is your favorite number? ---

    **Est o te viri tum mihi**

    Lorem markdownum nunc attenuarat pocula **{{question}}** atria ante est.

Est o te viri tum mihi

Lorem markdownum nunc attenuarat pocula What is your favorite number? atria ante est. Erat lacte neve vulnus audistis infelix sidera tuae 42 .

### package.json

The plugin loads `package.json` and make it available for Mustache as `package` variable.

    **Temerasse rerum taurus**

    Tum me modo leones verbis: meum mons Pirithoi conubia! Studio color sed erit
    ducitur leto contrahitur dolor est quodvis Aeolidis sororum **{{package.version}}**.

Temerasse rerum taurus

Tum me modo leones verbis: meum mons Pirithoi conubia! Studio color sed erit ducitur leto contrahitur dolor est quodvis Aeolidis sororum 1.0.5 . Rubentia sumit docsify-mustache .

package.json

### URL

Data can be loaded from relative or absolute URL. Both JSON and XML data file formats are supported.

    window.$docsify = {
      mustache: {
        data: ['doc/vars.json','data/pom.xml']
      }
    }

    **Aditus terras ignoto longa ad captis colunt**

    Inde pondera silva tantum glaebas tenetis ab **{{favorite.fruit}}**. Cunctas est orbem profatu
    erigitur maximus: in **{{project.version}}** figuris canes.

Aditus terras ignoto longa ad captis colunt

Inde pondera silva tantum glaebas tenetis ab raspberry . Cunctas est orbem profatu erigitur maximus: in 1.2.3 figuris canes. Oete iniaque stta in foo ego favent Penei. Lacertos tenebat veteres brown .

    {
      "favorite": {
        "fruit": "raspberry",
        "color": "brown"
      }
    }

    <project>
      <modelVersion>4.0.0</modelVersion>
      <groupId>com.example.app</groupId>
      <artifactId>foo</artifactId>
      <version>1.2.3</version>
    </project>

### JavaScript

Data can be loaded from Docsify’s JavaScript configuration.

    window.$docsify = {
      mustache: {
        data: {
          author: {
            name: 'John Smith',
            email: 'john.smith@example.com'
          }
        }
      }
    }

    **Viri coniuge resistit mariti**

    Aderat voluisti excipit caede meus celanda usus, **{{author.name}}**. Qua ad Pagasaea
    perenni pleno exprobravit dextra.

Viri coniuge resistit mariti

Aderat voluisti excipit caede meus celanda usus, John Smith . Qua ad Pagasaea perenni pleno exprobravit dextra. Nec heros rebelles ambiguus, sunt timuere suis; per fuerat, dixit muro john.smith@example.com undique, tanto satos.

## Merging

Mustache template data is actually merged from multiple different sources before the template is rendered. The order of priority for sources of data is (from highest priority to lowest):

1. Front Matter data in markdown document.
2. Data from plugin configuration. When `data` configuration option contains multiple source (as an array) then the latest data source will have the highest priority.

## License

This project is licensed under the MIT License. See the LICENSE for details.