introduction.pandoc

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

[menu]
  [menu.devguide]
    parent = "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](https://www.opengeosys.org/docs/benchmarks/elliptic/elliptic-neumann)
- You can preview documentation locally with [Hugo](https://gohugo.io) – a static site generator (minimum version: {{< dataFile "versions.minimum_version.hugo" >}})

## Requirements

- Download [Hugo](https://github.com/gohugoio/hugo/releases/latest) and put it in your `PATH`. **Attention:** Use the *extended* version: e.g. `hugo_extended_{{< dataFile "versions.minimum_version.hugo" >}}_Windows-64bit.zip`
- [Install Pandoc](https://pandoc.org/installing.html)
- Install [Yarn](https://yarnpkg.com/en/docs/install); for downloading required JavaScript & CSS development packages

## Getting started

- Inside the source-directory `ogs/web`:
  - Run `yarn` once (this will install required css and js packages)
  - Run `hugo server`
  - Open [http://localhost:1313](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:

```bash
hugo new docs/benchmarks/elliptic/groundwater-flow-dirichlet.pandoc
```

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

Or you can simply create a new `.pandoc`-file in the correct location and fill it by yourself.

### Setup navigation for a page

The are submenus (shown in the left sidebar) for specific sections such as for benchmarks. The submenus consist of groups (e.g. *Elliptic*) and page entries. Groups are defined in `config.toml`:

```toml
[[menu.benchmarks]]
  name = "Elliptic"
  identifier = "elliptic"
  weight = 1
```

To add your page to a group as an entry add the following frontmatter:

```toml
weight = 101

[menu]
  [menu.benchmarks]
    parent = "elliptic"
```

`weight` specifies the order of groups and pages in ascending order (top -> down).

### Write a page

We use [Pandoc Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) for the actual content.

It is an enhanced version of the [original Markdown](http://daringfireball.net/projects/markdown/). Please consult both guides!

#### Images

Use regular Markdown syntax:

```md
![](../square_1e2_neumann_gradients.png)
```

The path to the image can be absolute (by preceding with `/`) or relative. The relative path starts at your current URL. If your image is in the same directory as your `.pandoc`-file you have to prefix your path with `../` as in the example above.

See the [Pandoc Help](https://pandoc.org/MANUAL.html#images) for more options on e.g. image size and captions.

#### Equations

Equations can be set with typical LaTeX syntax by using [MathJax](https://www.mathjax.org/). Blocks are defined by `$$` at the beginning and `$$` at the end of the block. Inline math uses one `$` as the delimiter. For more usage instructions see the [MathJax LaTeX help](http://docs.mathjax.org/en/latest/tex.html).

#### Files and Downloads

Files belonging directly to a page (e.g. images shown on that same page) should be added directly (they are stored by git lfs). 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 with the [`bib`-shortcode](https://github.com/ufz/ogs/blob/f0ebe2e5c9507039a6776c7cb2989a35790bce2f/web/content/docs/benchmarks/bgr_verification_examples/thermomechanics.pandoc#L42-L46).


The bib-file has to be converted into a json-file with the [pandoc-citeproc](https://github.com/jgm/pandoc-citeproc)-tool:

```sh
[cd to ogs/web]
pandoc-citeproc --bib2json ../Documentation/bibliography.bib > data/bibliography.json
```

This json-file is then used by the shortcode.

---

## Advanced topics

### Update search index

```bash
ALGOLIA_WRITE_KEY=XXX node_modules/.bin/hugo-algolia --toml -s
```

### Used components

- [Hugo](https://gothugo.com) - Web site generator
- [Tailwind](https://tailwindcss.com/docs/what-is-tailwind) - CSS framework
- [FontAwesome](https://fontawesome.com) - Icons, see [icon search](https://fontawesome.com/icons?d=gallery)
- [Slick Carousel](http://kenwheeler.github.io/slick/) & [FancyBox](https://fancyapps.com/fancybox/3/) for image galleries
- [Algolia](https://github.com/algolia/algoliasearch-client-javascript) for site search

### Link checker

```
npm install -g @hashicorp/broken-links-checker
hugo
broken-links-checker --path ./public --baseUrl https://www.opengeosys.org
```