Writing Evolveum Documentation

The "docs" site is built using Jekyll static site generator, spiced up with Asciidoctor and other goodies. The site is generated from the "sources" into static HTML files. There is no dynamic interpretation of HTTP requests, however there is some client-side JavaScript to improve site presentation. Everything has to be generated before the first request comes, including headers, footers, navigation and everything else.

Site sources are maintained in GitHub docs repository. There is an automatic hook in github, that triggers rebuild of the site when the source code is updated.

Bulk of the documentation is maintained in AsciiDoc format. If you are new to AsciiDoc, brief primer follows shortly - but you better also check the official docs. If you are familiar with AsciiDoc, you can start writing your documents right away. Please, use the one sentence per line convention.

Use AsciiDoc whenever possible. Jekyll that runs this site allows also other documentation formats, such as HTML or Markdown. Use HTML only in case AsciiDoc would not do the job, or it would be very complicated. Do not use Markdown at all. We do not like Markdown here.

Site source code has almost exactly the same structure as the generated website. A picture stored as midpoint/foo/bar.png in the site source code will be published as https://docs.evolveum.com/midpoint/foo/bar.png. For text documents, Jekyll automatically converts them and hides file extension. Therefore midpoint/foo/bar.adoc becomes https://docs.evolveum.com/midpoint/foo/bar/.

AsciiDoc pages can be created in a very straightforward way. Just place your document in a suitable directory, make sure it has adoc extension and that’s it. The document should be well-formatted AsciiDoc document. In that case Jekyll takes all the data and meta-data from the document itself, properly setting document title, placing it in the navigation and all the other things. AsciiDoc is strongly recommended method of creating and maintaining documents. IntelliJ IDEA has a very convenient plugin for AsciiDoc editing. Developers and engineers would probably like to clone the site sources from gitlab and open them as a project in the IDEA.

While Jekyll does almost all the work transparently for AsciiDoc documents, other document types need a couple of additional things. Especially HTML documents usually need a place to specify document title and other meta-data. This place is called front matter, it is located at the beginning of the document:

In this case, the front matter sets document title, navigation title and display order. It also specifies page layout (see later), and it may also specify almost arbitrary data and meta-data for the page. Front matter is YAML-formatted. However, the most common form of front matter is just a simple attribute-value list as the one shown above.

AsciiDoc documents may also specify front matter, just as shown in the HTML example above. Additionally, AsciiDoc has its own Document Attributes mechanism. When you write front matter attributes using AsciiDoc attributes mechanism, add page- prefix to the attribute name. The front matter above can be rewritten with AsciiDoc attributes like this:

However, AsciiDoc documents usually do not need any front matter or attributes at all. E.g. in this case we did not even need to specify title and layout. Title was taken from AsciiDoc title, and page layout was applied by default. Everything is easier with AsciiDoc.

Site source code follows closely the resulting site structure, except for some URL translations. Such translations usually apply to asciidoc documents and index files (index.html, index.adoc). It is perhaps best to explain the URL translation on examples:

Which means that there are two ways how to store your document:

Both methods will results in the same URL. URL is all that matters for the web. You can change foo.adoc to foo/index.adoc at any time and Jekyll will generate the same URL. Therefore you can easily start with foo.adoc and then switch to foo/index.adoc later if needed.

We love links. Please, put a lot of links in your documents. There are two ways how to do it: link or xref.

Document table of contents (ToC) can be automatically generated. This mechanisms if controlled by page-toc asciidoc variable:

The variable may contain several values, changing the type of ToC:

Docs pages may easily include common "warnings" at the top of a page.

If you are using midPoint versions, it is recommended to enclose them in double quotes. Jekyll interprets variables as JSON/YAML, therefore version 1.10 will be interpreted as number. The it will be considered to be the same as 1.1. Specifying the version quoted as "1.10" solves the problem.

Jekyll is using Liquid templating language. If is very simple templating language that is using "curly bracket" markup: {{, }}, {%, %}. Liquid can be used to add basic logic to the documents, such as this:

See Liquid documentation for the details.

There are some custom Liquid tags that are implemented by Evolveum plugin, such as {{ children }}.

Most of the files in the Jekyll project are documents. But there are some special directories and files:

Generally speaking, the files and directories that start with an underscore (_) are not directly translated to website content. Such files influence the way how the site behaves. However, many files are transformed to website content indirectly. E.g. the SASS stylesheets in _sass are transformed to CSS and published on the website.

Navigation is an important aspect of a website that is packed with documents. There was no ready-made navigation mechanism for Jekyll, therefore we had to develop our own. It is part of Evolveum Jekyll plugin and supported by Evolveum theme.

The navigation tree generated automatically for all documents on the site. There is nothing special to do when a new document is added. It will be automatically added to the navigation tree. However, you may want to customize the way how the navigation mechanism displays your document.

Jekyll (or rather our plugin) will generate "stub" pages for documents that are missing in the tree. For example, let’s assume that we have foo/bar.adoc and /foo/baz.adoc, but we do not have foo.adoc nor foo/index.adoc. In that case Jekyll will automatically generate "stub" for /foo/. The "stub" is a simple page that just lists the children pages.

The stub will have an ugly title, derived from the URL. In the above example, the title of the stub will be simply foo. Therefore it is still recommended to explicitly create a simple page:

You may want to hide entire subtree. This can also be achieved with a simple index document:

This document hides the entire foo/* subtree, as the navigation algorithm will not dive into a hidden page. However, page breadcrumbs will still work, even in the hidden subtree. Therefore other documents in the subtree may be discovered using breadcrumbs.

Generally, the pages should not be moved. Once the page is created on a certain URL, it should stay on that URL. Of course, it is OK to change foo.adoc to foo/index.adoc, as the URL stays the same. But the pages should not be moved in a way that changes the URL.

When the page really needs to be moved, there is a mechanism how to leave behind a redirect from the old URL to new URL:

The moved-from attribute specifies the local part of the old URL. Jekyll will generate a redirect from the old URL to a new URL of the page. In this case, Jekyll will redirect /midpoint/support/ to /support/.

In a case that an entire subtree needs to be moved, the * notation can be used to set up a subtree redirect:

Various page attributes can be set in page front matter. The attributes usually add meta-data to the page, used for better indexing, and search optimization.

The attributes are summarized in the following table.

Some attributes must be explicitly placed in front-matter. This is necessary due to the order of Jekyll operations when building the page. There is no difference for HTML files, however, asciidoc files need an explicit front matter at the beginning:

Jekyll data files are small databases that can be used to hold structured data. The data files are placed in the _data directory. The files are formatted in YAML, like this:

The files are usually used in HTML pages, with a help of Liquid tags:

The talks.yml data file will be present in Liquid variable site.data.talks. As the content of talks.yml file represents a list, the content of site.data.talks can be processed by simple for liquid tag.

Liquid tags {% and %} control the flow of the template. The {{ and }} tags are used for displaying data. The {{ talk.data }} and {{ talk.author }} refer to the date and author fields in the talks.yml file.

Simple, isn’t it?

If you want to create a new database, just create a new _data/foo.yml file and fill it with data. Content of the file will be present in the site.data.foo variable.

MidPoint documentation is big and complex, it is often difficult to navigate. Therefore we have introduced concept of "feature", which helps to organize the documentation. It also helps to see what midPoint can do, how it relates to compliance and so on.

List of midPoint features is maintained in midpoint-features.yml data file. The file is used to generate feature pages with subpages describing every feature, linking to documentation, compliance frameworks and other parts of midPoint documentation.

Any page in midPoint documentation can be marked as describing a particular feature or features. The marking can be done in front matter:

The midpoint-feature must reference feature identifier, as it is recorded in midpoint-features.yml. If the page relates to more than one feature, they all should be mentioned in a form of list:

The doc-type attribute can be used to denote documentation type:

When in doubt, use config doc-type.

Jekyll layouts are templates to construct particular type of page. The most common layout is page, which is used for vast majority of pages in our sites. The page layout has a pre-set formatting for page title, breadcrumbs, navigation tree and all other necessities. However, sometimes there is a need for a different layout. For example, site home page (landing page) usually does not have a title. Having empty HTML tags for the title can ruin the design. Therefore, there is special home layout that is almost the same as page layout, but it does not have a title.

Evolveum theme contains following layouts ready to be used:

You can create your own custom layouts if you need to. Just place them into the _layouts directory. You can use the exercise layout on docs as an inspiration.

Site look and feel is given by stylesheets (SASS and CSS) combined with the layouts. Layouts dictate which HTML elements are used in the page, stylesheets specify how the elements look like.

The design is a living thing. The design has to be responsive, it has to adapt to various devices. We want to display rich navigation tree on big notebook displays, but we do not have a place for that on mobile phones. Creating stylesheets for such a design is a difficult work. Therefore we are not starting from scratch. We are basing our design on Bootstrap framework.

The stylesheets are created and maintained in a form of Syntactically Awesome Style Sheets (SASS). The SASS files are automatically compiled into ordinary CSS files by Jekyll. Most of the stylesheets are part of Evolveum theme and there is usually no need to change them. Some look and feel of the site can be adapted by changing values of SASS variables.

There is a special Evolveum theme applied to this site. The theme specifies basic site design, such as CSS/SASS styles and HTML page templates. The theme contains stylesheets (SASS), page layouts, fonts, icons, evolveum logo and anything else that is used on all our sites. The theme has file structure that is almost the same as Jekyll site structure.

The theme is supplemented by Evolveum Jekyll plugin, which adds more complex elements, such as the navigation. The plugin is a small piece of Ruby code that add some features to Jekyll.

Both the theme and the plugin are designed to be used as Ruby gems. There is a build.sh script that builds and installs the gems.

The use of the theme and the plugin is specified in _config.yml file in the site.

When the site refers to page layout, that layout is taken from the theme, from _layouts directory. Our page layout file (_layouts/page.html) specifies the structure of pages on our sites. This layout contains Liquid tags to render navigational elements ({% breadcrumbs %}, {% navtree %}). These are custom Liquid tags that are implemented in evolveum-jekyll-plugin.

Asiidoc supports formatting of tables, although the actual markup may look scary at first. It looks like this:

Which renders a table:

The |==== delimiters mark table boundaries. Don’t forget to use it also at the end, otherwise an error will be reported during the build of the site.

First line specifies table header (English, Slovak and Latin). These have to be all on the same line, separated by pipes (|). Having them on the same line means that this is a header, otherwise the asciidoc would render it as a plain content.

Each row of the table is specified by a block of lines, each line starting with a pipe (|). There has to be at last one line for each column. There must be exact number of the lines starting with pipes to fill all the cells of the table.

The [%autowidth] at the beginning means that asciidoc will set column widths (and table width) automatically, based on the content of table cells. It is recommended to use the [%autowidth] for all ordinary tables. If you need a more sophisticated table column layout, there are many options to choose from.

Sometimes you want to use special characters as if they are not special. What you need is to avoid the processing and substitutions. There is a couple of mechanisms to do that, depending on the scope of your need:

Please note that the content of docs site is licensed under the terms of Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0) license. There are limitations to the use of both the content of the site, and its source code. Please also note, that the license does not cover use of trademarks, which may be used on this site.

Generally speaking, Contributor License Agreement (CLA) is needed to contribute to the content of this site.

Please see General Copyright and Licensing Guidelines for details.

Most of the documentation on this site was migrated from Evolveum Wiki, that was used to maintain the documentation before 2021. There is some legacy from the old times, such as the pages contain wiki-name and Wiki metadata variables.

It is a good idea to add a dedicated See Also section - like this one - at the end of your document. Provide links for the reader to dig deeper, to follow up on related topics.