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
_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
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
Copy and paste the contents and add the frontmatter.
--- title: Configuration Basics permalink: configuration-basics.html keywords: configuration, basics, overview summary: "Usually the first paragraph of the page. If not create one or simple leave the field blank" ---
In the majority of cases the first paragraph will naturally lend itself to be the
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.
Kramdown tries to aggressively create tables out of pipes, so || x ||_2 will become
\|\| x \|\|\_2
Should there be any images in the article, copy them to the
images folder and link them as follows:
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:
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
advancecall (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`