docmodel show menu hide menu

Versions and Languages

docmodel can organize your documents into version and language collections. In fact, docmodel always organizes your documents into version and language collections--it simply applies default collections if you don't define any. By making some small changed to your configuration file, and following some simple conventions, you can:

Define Versions

To group your documents into version/languages groups, you will need to use special keys in the route of your configuration file's documents object. These keys will take the form #version:language-code where version can be any value not containing a colon (:) character, and language code is a 2 character ISO 639-1 language code.

Building on the simple document list shown in the Getting Started guide, the following list groups the documents from there into a collection where the version will be 0.1.0 and the language will be en (English). Other configuration properties have been omitted for clarity:

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

If you add a latest_version key to your configuration file, baked documents from any other version will automatically include an "outdated" warning which links to the latest version. See the section on Configuration for more.

For clarity: your versions names do not have to be semantic version numbers, these have just been used as an example. The following is just as valid:

"documents": {
  "#Really Cool Version Name:en" {
    "Getting Started": "getting-started.md"
  }
}

By contrast, your language codes must be ISO 639-1 compliant.

Create Relationships

docmodel considers 2 documents related translations when replacing the language code in one document's source path with another supported language code creates a match to the other document's source path. As example: foo-en.md and foo-de.md are related translation. Similarly, docmodel considers 2 documents related versions when replacing the version name in one document's source path with another supported version name creates a match to the other document's source path. As example: 0.1.0/foo-en.md and 0.2.0/foo-en.md are related versions.

It's worth noting that matches rely on replacement, not difference. As such, foo-.md and foo-en.md are not related translations as the first one does not contain a language code. With this in mind, you should following the relationship convention from the start of your project--for better future proofing. Here's a simple example of how you can organize your files using this convention (one example, there are other ways you can achieve the same effect):

"documents": {
  "#0.1.0:en": {
    "Getting Started": "0.1.0/getting-started-en.md"
  },
  "#0.1.0:nl": {
    "I Don't Actually Speak Dutch": "0.1.0/getting-started-nl.md"
  },
  "#0.2.0:en": {
    "Getting Started": "0.2.0/getting-started-en.md"
  },
  "#0.2.0:nl": {
    "Still Haven't Learned It!": "0.2.0/getting-started-nl.md"
  }
}
« PreviousNext »