docmodel show menu hide menu

$include and $extend

The larger your documentation project gets, the more unwieldy your configuration file is going to become. To make your life a little easier, docmodel provides two special directives you can include in your configuration file (docmodel.json) to $include other JSON files, or to $extend other objects.

Both of these directives are single-pass
i.e. you cannot $include inside of another $include file

$include

The $include directive can be used to include the contents from another JSON file and set them as the value of a local property. These files will be included relative to your project's docmodel directory (which would be better named include, but it's done now). Here's an example:

[project]/docmodel/0.1.0-en.json contents:

{
  "Getting Started": "0.1.0/getting-started-en.md", 
  "Something Else" : "0.1.0/something-else-en.md", 
  "A Section": {
    "Foo"             : "0.1.0/foo-en.md",
    "Bar"             : "0.1.0/bar-en.md",
    "A Nested Section": {
      "Baz": "0.1.0/baz-en.md"
    }
  }
}

[project]/docmodel.json snippet (omitting other properties for clarity):

"documents": {
  "#0.1.0:en": {"$include": "0.1.0-en.json"}
}

Note that .json at the end of the include path is optional. It's also worth noting that when you use an $include directive the full contents of its containing object will be replaced with the included contents. In the following example, the More entry will be wiped out:

[project]/docmodel.json snippet (omitting other properties for clarity):

"documents": {
  "#0.1.0:en": {
    "$include": "0.1.0-en",
    "More"    : "will-not-be-included.md"
  }
}

Includes are processed before extends.

$extend

Let's imagine a situation where you want to create a new version that is essentially the same as an older one, but with some files replaced, or new files added. This is where the $extend directive comes into place. In the following example, we add a 0.2.0 version which extends 0.1.0, overriding one entry (Something Else), and adding a new file (Just for 0.2.0):

"documents": {
  "#0.1.0:en": {"$include": "0.1.0-en.json"}, 
  "#0.2.0:en": {
    "$extend"       : "#0.1.0:en",
    "Something Else": "0.2.0/something-else-en.md",
    "Just for 0.2.0": "0.2.0/just-for-020-en.md"
  }
}

Note that the value for an extend directive is simply another object key. In the example above we extended the #0.1.0:en object, but we could just as easily have extended any other object in the JSON file. However, do keep in mind that these directives are single pass.

The $extend directive performs a deep merge on the original and current objects. Extends are processed linearly, so the object you are extending must be before an $extend directive in your configuration file.

Extends are processed after includes.

« PreviousNext »