Writing web documentation

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: 0.146.0)
• 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_0.146.0_Windows-64bit.zip
• Install Yarn; for downloading required JavaScript & CSS development packages
• Install npm for CSS / JavaScript compilation with npx
• A configured build-directory

Getting started

• Inside your build-directory:
  • Build the web-target, this creates the web site in [build-dir]/web/public, or
  • build the preview-web-target, which starts a Hugo server where you can preview the site at http://localhost:1313.

As you make modifications to the site it will be rebuild and the page in the browser gets reloaded when then preview server is running.

To manually build the site:

cd [build-dir]/web
yarn
yarn build
# OR
yarn server

To view all available yarn commands run yarn run.

Executed Jupyter notebooks show up in the preview server too, e.g. in your build-directory:

ctest -R nb- -j 4 # Runs all available notebooks
ninja preview-web
# If not opened automatically, open http://localhost:1313 in your browser

How-Tos

Create a new page

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 S3 storage).

Bibliography references

Bibliography items from any .bib-file in web/content/publications/ can be referenced by their cite key with the bib-shortcode:

{{< bib "Kolditz2012" >}}

produces

@article{Kolditz2012,
 abstract = {In this paper we describe the OpenGeoSys (OGS) project, which is a scientific open-source initiative for numerical simulation of thermo-hydro-mechanical-chemical processes in porous media. The basic concept is to provide a flexible numerical framework (using primarily the Finite Element Method (FEM)) for solving multifield problems in porous and fractured media for applications in geoscience and hydrology. To this purpose OGS is based on an object-oriented FEM concept including a broad spectrum of interfaces for pre- and postprocessing. The OGS idea has been in development since the mid-eighties. We provide a short historical note about the continuous process of concept and software development having evolved through Fortran, C, and C++ implementations. The idea behind OGS is to provide an open platform to the community, outfitted with professional software-engineering tools such as platform-independent compiling and automated benchmarking. A comprehensive benchmarking book has been prepared for publication. Benchmarking has been proven to be a valuable tool for cooperation between different developer teams, for example, for code comparison and validation purposes (DEVOVALEX and CO2 BENCH projects). On one hand, object-orientation (OO) provides a suitable framework for distributed code development; however, the parallelization of OO codes still lacks efficiency. High-performance-computing efficiency of OO codes is subject to future research.},
 author = {Kolditz, O. and Bauer, S. and Bilke, L. and Böttcher, N. and Delfs, J. O. and Fischer, T. and Görke, U. J. and Kalbacher, T. and Kosakowski, G. and McDermott, C. I. and Park, C. H. and Radu, F. and Rink, K. and Shao, H. and Shao, H. B. and Sun, F. and Sun, Y. Y. and Singh, A. K. and Taron, J. and Walther, M. and Wang, W. and Watanabe, N. and Wu, Y. and Xie, M. and Xu, W. and Zehner, B.},
 category = {Methods},
 day = {01},
 doi = {10.1007/s12665-012-1546-x},
 issn = {1866-6299},
 journal = {Environmental Earth Sciences},
 month = {Sep},
 number = {2},
 pages = {589-599},
 title = {OpenGeoSys: an open-source initiative for numerical simulation of thermo-hydro-mechanical/chemical (THM/C) processes in porous media},
 volume = {67},
 year = {2012}
}

Other shortcodes

# Creates a link to the project-parameter on a benchmark page
{{< data-link >}}

produces

# Creates a URL to the given file in Tests/Data
{{< data-url "Elliptic/cube_1x1x1_SteadyStateDiffusion/drainage_excavation.prj" >}}

https://gitlab.opengeosys.org/ogs/ogs/-/blob/6.5.8/Tests/Data/Elliptic/cube_1x1x1_SteadyStateDiffusion/drainage_excavation.prj

# Reads the versions.json file outputs values
{{< dataFile "versions.minimum_version.gcc" >}}

13.3.0

# Outputs the pip package. Use this to have consistent package
# version on the versioned web pages.
{{< ogs-pip-package >}}

ogs==6.5.8

# Outputs the pip package of ogstools. Use this to have consistent package
# version on the versioned web pages.
{{< ogstools-pip-package >}}

ogstools

# Produces 'master' or current tag for releases.
# Use this to construct consistent links to links to files.
{{< repo-ref >}}

6.5.8

Used components

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