Data

You can add custom data to Doxicity. The data you provide will be made available to all pages through the use of Handlebars expressions in your markdown.

Providing Data

Two types of data can be provided. The first type is config data, which is globally available to all pages. The second type is page data, which is only available on the page it’s provided on. A third type of data, called magic properties, will be provided by Doxicity.

Page data will be merged with config data when published, meaning page data can override config data if fields of the same name are used. This is by design, as it allows you to specify fallback values in your config and override them on selected pages. A deep merge algorithm is used, so you can override specified properties without having to redefine entire objects.

Config Data

As its name implies, config data is provided through your Doxicity config. You have complete control over the data you provide here. However, with great power comes great responsibility. It’s up to you to structure your data in a way that scales with your documentation.

You can set custom data in your config file using the data property. The object is flexible enough to hold any type of value, including arrays and objects.

import Doxicity from 'doxicity';

const dox = new Doxicity({
  // ...

  data: {
    name: 'Bob Marley',
    occupation: 'Entertainer',
    songs: [
      /* ... */
    ]
  }
});

          

          
        

Page Data

In addition to config data, page data can be provided by prepending front matter to your markdown files. An important thing to consider is that config data and page data will be merged before each page is rendered. This is by design, so you can supplement and/or override config data on a per-page basis.

Front matter is an elegant format that uses YAML to provide data within a markdown file. If that sounds complicated, perhaps an example will clear things up.

---
title: Hello, world!
description: Just a page to demonstrate front matter.
items:
  - Item 1
  - Item 2
  - Item 3
---

# Your content begins here

          

          
        

This is equivalent to the following JavaScript object:

const data = {
  title: 'Hello, world!',
  description: 'Just a page to demonstrate front matter.',
  items: ['Item 1', 'Item 2', 'Item 3']
};

          

          
        

Magic Properties

Magic properties are available to all pages and are always prefixed with $. The following magic properties are currently provided.

Avoid prefixing top-level config data and page data fields with $, as this is reserved for future magic properties.

Consuming Data

As mentioned earlier, Handlebars expressions are used to consume data in your pages. You can output selected data, selectively render content using conditionals, loop through arrays and objects, and even pass data to partials.

Let’s consider the following markdown file.

const data = {
  occupation: 'Zoologist',
  animals: [
    { name: 'Cat', size: 'small' },
    { name: 'Mouse', size: 'really small' },
    { name: 'Elephant', size: 'giant' }
  ]
};

          

          
        

Now let’s consider the following Handlebars expressions in this contrived markdown file.

---
name: Zoe Zookeeper
occupation: Zoologist
isEmployed: true
animals:
  - name: Cat
    size: small
  - name: Mouse
    size: tiny
  - name: Elephant
    size: gigantic
---

My name is {{name}} and I'm a {{occupation}}.

{{#if isEmployed}}
  I am currently employed!
{{else}}
  I am currently unemployed and open to new opportunities!
{{/if}}

My favorite animals are:

{{#each animals}}
- {{this.name}} which is a {{this.size}} creature
{{/each}}

          

          
        

The resulting HTML will be:

<p>My name is Zoey Zookeeper and I am a Zoologist.</p>
<p>I am currently employed!</p>
<p>My favorite animals are:</p>
<ul>
  <li>Cat which is a small creature</li>
  <li>Mouse which is a tiny creature</li>
  <li>Elephant which is a gigantic creature</li>
</ul>