Contact Inkit

Writing content

Content for a DocGen website is authored either in:

  • plain text (.txt files)
  • markdown (.md files)
  • HTML (embedded in .md files)

You can use any text editor or IDE to edit these. The advantage of markdown is that it will be automatically styled (e.g. headings, bullet points etc).

Image files can be embedded (via links), and other files can be attached (the website will link to these).

Additionally, some website metadata is configured via JSON files.

Overview

DocGen transforms source files from an input directory into output files in an output directory.

It takes every source file (plain text) specified in contents.json and converts it. Each source file becomes a separate page in the website and a separate chapter in the PDF.

DocGen adds metadata that is specified in parameters.json, and copies the images and files in the files directory to the output.

Always save input files with UTF-8 encoding. This makes non-standard characters (ø © é etc.) work.

Metadata

parameters.json

The parameters file is used to specify metadata describing the product.

  • title - the website title
  • name - the website name (also used to name the PDF)
  • version - the release version
  • date - the release date
  • organization - the company or organization
  • author - the lead author of the document
  • owner - the owner of the document
  • contributors - list of contributors
  • website - a link to the parent website
  • backlink - a link back to another site (useful for integrated documentation)
  • module - module name (useful for larger sites with submodules)
  • id - reference number (e.g. id in a change management tool)
  • summary - a descriptive summary of the website/document
  • marking - license or other protective markings
  • legalese - document markings (confidentiality, disclaimers, smallprint etc)

Values can be empty strings, but the elements are required in the JSON file.

Parameters with URLs can be either website URLs, or email addresses (specify 'mailto:name@address.com').

contents.json

The contents file specifies the names, locations, order, and hierarchy of the source files. It is used to generate both the web and PDF table of contents.

release-notes.md

The release notes source file is a mandatory source file (that does not need to be listed in contents.json). Use it to summarize the change history for each version of the product.

Plain text

The simplest input format is just to write in plain text. Here is an example of the source and output:

Example paragraph.

Example paragraph.


Markdown

Markdown is a human-friendly plain text markup format. The source format is easy to read and write, and the CommonMark parser translates it into HTML. DocGen uses the CommonMark standard via a package called markdown-it. Here is an example of the source and output:

Markdown Example
------------------

Paragraphs are text blocks separated by new lines.

Text can be styled: *emphasised* and **strong**.

Here is an [example link](http://www.google.com).

  # To make a code block, just indent with a tab
  # "Hello World" in Ruby:
  5.times { puts "Hello!" }

Markdown Example

Paragraphs are text blocks separated by new lines.

Text can be styled: emphasised and strong.

Here is an example link.

# To make a code block, just indent with a tab
# "Hello World" in Ruby:
5.times { puts "Hello!" }

For more examples, see the CommonMark reference.

HTML

For more complex pages not covered by CommonMark's syntax, simply use inline HTML:

<table>
  <tr>
    <td>Foo</td>
    <td>Bar</td>
    <td>Baz</td>
  </tr>
</table>
Foo Bar Baz

For more examples, see writing advanced content.

Inline HTML is still parsed by the CommonMark parser (HTML is allowed in CommonMark documents). In DocGen, it is also possible to bypass the CommonMark parser altogether and specify a pure HTML input page, by setting "html": true in a page object in contents.json.

Embedding images

Diagrams (in image form, e.g. JPEG, PNG, GIF etc.) should be put the files/images directory, and embedded as image links.

![logo](files/images/logo.svg)

Icons

DocGen ships with Tabler Icons built-in (a modern, open-source SVG icons library). You can insert icons in content pages by adding an HTML span tag with the dgIcon class, and the name of the icon in data-name attribute. You can also add optional classes to customize the icon styles.

Example:

<span class="dgIcon" data-name="graph-filled"></span>

You can use built-in classes to customize icon styles (small, large, info, warning, success, error).

Size:

Color:

Custom colors:

You can apply custom colors with a style attribute.

Attaching files

Other files you want to attach should go into files directory.

[attachment](user_guide.pdf)
attachment

Mathematical Expressions

LaTeX is the most common markup format for mathematical expressions.

Modern web browsers do not yet consistently support a common standard for authoring mathematical expressions. For this reason, extra libraries are needed. DocGen supports two widely-used web mathematics libraries out-the-box:

The document author decides which one (or both) to use.

Mathematics using KaTeX

KaTeX is the recommended choice. It is bundled with DocGen but must be enabled by passing the -m option.

<div class="dg-katexMath">
f(x) = \int_{-\infty}^\infty
    \hat f(\xi)\,e^{2 \pi i \xi x}
    \,d\xi
</div>
f(x) = \int_{-\infty}^\infty \hat f(\xi)\,e^{2 \pi i \xi x} \,d\xi

Mathematics using MathJax

MathJax is the fallback choice for expressions not yet supported by KaTex. When required, MathJax can be enabled by passing the -n option.

DocGen uses the same MathJax configuration as the popular Stack Exchange websites.

Because MathJax is a large library, it is not bundled with DocGen, but is served from a third-party CDN (content delivery network). This means users need an active Internet connection for the MathJax feature to work.

MathJax can be slow to render. When used with the PDF feature, it may be necessary to allow more rendering time by passing the
-d [milliseconds] option. 

$$
f(n) = \begin{cases}
    n/2,  & \text{if $n$ is even} \\
    3n+1, & \text{if $n$ is odd}
    \end{cases}
$$
$$ f(n) = \begin{cases} n/2, & \text{if $n$ is even} \\ 3n+1, & \text{if $n$ is odd} \end{cases} $$