date = "2018-02-23T15:28:13+01:00"
title = "Writing web documentation"
author = "Lars Bilke"
weight = 1024

[menu.devguide]
parent = "development-workflows"

aliases = ["/docs/devguide/documentation/introduction/"]

The big picture

• Development related content such as developer guide, benchmark documentation, tools description, ... are simple Markdown files in e.g. /web/content/docs
• You can preview documentation locally with Hugo – a static site generator (minimum version: {{< dataFile "versions.minimum_version.hugo" >}})
• A preview is also generated during Continuous Integration:

Benchmark documentation can also be given in form of Jupyter Notebooks, see Jupyter notebooks as documentation for details.

Requirements

• Download Hugo and put it in your PATH. Attention: Use the extended version: e.g. hugo_extended_{{< dataFile "versions.minimum_version.hugo" >}}_Windows-64bit.zip
• Install Yarn; for downloading required JavaScript & CSS development packages

Getting started

• Inside the source-directory ogs/web:
  • Run yarn and yarn build once (this will install required CSS and JavaScript packages)
  • Run hugo server
  • Open http://localhost:1313

As you make modifications to the site it will be rebuild and the page in the browser gets reloaded.

How-Tos

Create a new page

By using hugo new you can create a new page with the correct frontmatter for that kind of page:

hugo new --kind benchmark docs/benchmarks/elliptic/groundwater-flow-dirichlet/index.md

• path is relative to content/ and determines the URL of the page

Or you can simply create a new index.md-file in the correct location and fill it by yourself. Prefer to use page bundles when you want to add other assets, e.g. images, to the page.

content/
├── docs
│   ├── my-post
│   │   ├── image1.jpg
│   │   ├── image2.png
│   │   └── index.md

Page meta data

Page meta data is given in frontmatter.

• weight: Navigation is handled automatically by the folder structure. Use the weight-parameter in the frontmatter to specify the order of pages in ascending order (top -> down).
• image: Specify an image in the page bundle used for the gallery view.

Write a page

We use Markdown for the actual content. Hugo uses the GoldMark Markdown parser with the following additional markdown extensions:

• Definition lists
• Footnotes
• Autolinks
• Strikethrough
• Table
• TaskList
• Typographer

Images

Use regular Markdown syntax:

![Alt text](square_1e2_neumann_gradients.png "Caption text")

The path to the image is the relative path to the current page bundle.

You can add size attributes to the filename with a #-character:

![Alt text](square_1e2_neumann_gradients.png#two-third "Caption text")

Possible size values are one-third, one-half and two-third.

For even more flexible image handling you can use Hugo's figure-shortcode, e.g.:

{{</* figure src="elephant.jpg" width="50%" title="An elephant at sunset" */>}}

Or for two images side-by-side:

{{</* figure src="image_left.png" class="w-1/2 float-left" */>}}
{{</* figure src="image_right.png" class="w-1/2 float-left" */>}}

Equations

Equations can be set with typical LaTeX syntax by using MathJax. Blocks are defined by $$ at the beginning and $$ at the end of the block or by simply using a LaTex environment like \begin{equation}...\end{equation}. Inline math uses one $ as the delimiter. For more usage instructions see the MathJax LaTeX help.

Files and Downloads

Files belonging directly to a page (e.g. images shown on that same page) should be added directly. Other stuff such as linked PDF files, book chapter input files should be uploaded elsewhere and linked to. You can ask @bilke to host these files for you (on Azure cloud storage).

Bibliography references

Bibliography items from Documentation/bibliography/.bib can be referenced by their id (always use lowercase ids) with the bib-shortcode:

{{</* bib "kolditz2012" */>}}

The bib-file has to be converted into a yaml-file with the pybtex-convert-tool:

pipx run --spec pybtex pybtex-convert Documentation/bibliography/ogs.bib web/data/bib_ogs.yaml
pipx run --spec pybtex pybtex-convert Documentation/bibliography/other.bib web/data/bib_other.yaml

This yaml-file is then used by the shortcode.

Advanced topics

Update search index

TODO:

Used components

• Hugo - Web site generator
• Tailwind - CSS framework
• FontAwesome - Icons, see icon search
• Slick Carousel & FancyBox for image galleries