Generating documentation

Publish your models as markdown

Not everything CrossGenerate produces is code. This example generates markdown documentation for a whole data model - a table of contents plus a section for every entity, relationship and mapping - so people who do not use CrossModel can still read your models.

It is also the best example to study if you want to learn how to split a template into includes, because it uses five files instead of one.

How it works

CrossGenerate has no opinion about what it produces - it renders a template against a model object and writes the result to a file. Nothing in it is SQL-specific. Point the same machinery at a markdown template and you get documentation instead of DDL.

This template's scope is DataModel, the broadest of the scopes, so one run covers a whole model rather than a single entity. From that one object the template can reach everything beneath it: the entities, their attributes, the relationships and the mappings. That is what makes a single page with a table of contents possible.

It is split into five files because a data model page has repeating parts. The main template handles the page structure and delegates each repeating block - an entity, a relationship, a mapping - to an include. This is the pattern to copy whenever a template outgrows one screen, regardless of what you are generating.

The practical consequence is that your documentation stops drifting. It is generated from the same models the code generation uses, so it cannot describe a model that no longer exists.

Get the workspace

On the welcome page, under Tutorials & Examples, choose:

examples → code-generation → documentation → nunjucks (or handlebars)

What's in the workspace

Path	Purpose
`BrightGreen/Generation/Templates/datamodel/DataModelDocumentation.njk`	The main template. Scope: DataModel
`BrightGreen/Generation/Templates/datamodel/menu.njk`	Include - the table-of-contents sidebar
`BrightGreen/Generation/Templates/datamodel/entity.njk`	Include - one entity block
`BrightGreen/Generation/Templates/datamodel/relationship.njk`	Include - one relationship block
`BrightGreen/Generation/Templates/datamodel/mapping.njk`	Include - one mapping block
`BrightGreen/Generation/Output/Documentation/`	Example output, one markdown file per data model

Because the example output is committed to the branch, you can read the finished markdown before generating anything yourself.

How includes are resolved

Nunjucks resolves includes relative to the directory of the main template. All five files sit in Templates/datamodel/, so the main template can include entity.njk directly. Keep that in mind if you reorganise the folders - moving the main template breaks the includes.

Generate the documentation

Open CrossGenerate from the right-hand bar, or from View → CrossGenerate.
Select a DataModel - JuiceERP, PreciseFinance or example-dwh - or choose All Data Models.
Choose engine Nunjucks (or Handlebars).
Select main template DataModelDocumentation.njk.
Set the output filename pattern to {{datamodel.id}}.md.
Set the output directory, for example Generation/Output/Documentation.
Press Generate.

Each data model becomes one markdown file containing a table of contents and sections for its entities, relationships and mappings.

What to try next

Publish it. The generated markdown drops straight into a MkDocs, Docusaurus or GitHub Pages site - or into a repository wiki.
Include your own properties. If you have added custom properties via type definitions, extend entity.njk to render them. That is how you get house-standard metadata - ownership, classification, retention - into the published documentation automatically.
Regenerate on every change. Because the output is deterministic, committing it means every model change shows up as a readable diff in your pull requests.