Documentation migration guide

We describe a typical migration workflow for documentation pages from the (old) preCICE Github Wiki to the current jekyll-based system.

Edit me

0. Get the wiki

The Github wiki is a git repository consisting mainly of Markdown and image files. Get a local copy with

git clone https://github.com/precice/precice.wiki.git

1. Choose a section and map out the structure

It is advisable to start with the sidebar.yml in _data/sidebars. But before choose a self-contained set of pages that you want to migrate (or create), ideally a complete section like ‘configuration’ that can be ported in a single working session. As a next step flesh out the high-level structure, including file names and hierarchy. Don’t rush this part, as naming is the most difficult thing in programming.

When finalised, document your choices in the sidebar.yml.

2. Migrate pages one-by-one

The URL in the Github Wiki will indicate the Markdown file name, e.g. https://github.com/precice/precice/wiki/Basic-Configuration is generated by Basic-Configuration.md.

Copy and paste the contents and add the frontmatter.

---
title: Configuration Basics
permalink: configuration-introduction.html
keywords: configuration, basics, overview
summary: "Usually the first paragraph of the page. If not create one or simple leave the field blank"
---

Adapt title, permalink and keywords.

In the majority of cases the first paragraph will naturally lend itself to be the summary.

Note: The summary doesn’t support rich content such as variables, italic/bold or links. Keep it regardless as even the bare ASCII will add structure and our audience is used to reading raw code. In case the summary contains a link the sentence should most likely be part of the body and not the summary anyways.

3. Fix known issues

There are a number of minor issues which mostly stem from the slight differences in Markdown flavour.

H1 –> H2

In the Github Wiki Markdown files headlines usually are H1 tags (# in Markdown). This makes sense relatively but not absolutely in the context of the site, because you loose the possibility to declare a title (which needs to be H1) - example.

Therefore add another # to make headlines ## (and so on). Also note that the automatic TOC generation will only pick up on H2 and lower.

Wiki –> Documentation

Replace the term ‘wiki’ with ‘documentation’ as we are moving away from the Github wiki structure.

Escape pipes `\|`

Kramdown tries to aggressively create tables out of pipes, so || x ||_2 will become

Instead write

 \|\| x \|\|\_2

Migrate images

Should there be any images in the article, copy them to the images folder and link them as follows:

![atlernative text](images/image.png)

Fix links

Fixing links will likely be the most effort-intensive migration step. Try to fix links within the section you are migrating, and, if you can, also links to sections that have been migrated already.

All other links have to be fixed in a second pass.

For reference here is a valid link:

[Mapping Configuration](configuration-mapping.html)

Handle Markdown code in HTML blocks

While the Github Wiki automatically rendered Markdown within HTML tag blocks, we have to explicitly declare that Markdown should be expressed. This can be done by adding the markdown="1" attribute. Example:

<details markdown="1">
* `regular-prior`: In every `advance` call (also for subcycling) and in ...
</details>

will correctly render to

regular-prior: In every advance call (also for subcycling) and in …

4. Do some housekeeping

While you are at it, it makes sense to improve the documentation in general and its readability in particular.

It could be little issues such as

Improve the white space before and after blocks of code.
Check whether code has syntax highlighting enabled and add e.g.
```
    ```xml
    <xml>
    </xml>
    ```
```
Correct inline code snippets from
```
   ```variable``` --> `variable`
```