To edit documentation md files in this repository, all you need to do is to:
For Apple and Linux users, after installing hugo and VSCode, run:
make local-serve-and-edit # or hugo-serve-and-editand there will be an extra icon in the title bar of the site:
which should open the current page in VSCode.
For other editors see the note at the bottom of the page.
In Windows Powershell (assuming there are no spaces in your pwd):
.\serve_and_edit.ps1All Hugo site content is stored under the /content folder.
The main documentation is specifically in /content/en.
The file and folder layout matches what you see in the URL bar of your browser.
Hugo supports internationalization (i18n), the content for each language is stored in a 2 or 3 char ISO 639 code.
Therefore documentation for a particular language will be found in /content/<lang>, for example /content/fr.
There are two ways to create a page:
- copy another page
- use Hugo (preferred):
From the root of the repository:
hugo new docs/corda-os/4.4/my-new-page.mdThis will produce a new file in /content/en/docs/corda-os/4.4/my-new-page.md
---
title: "My New Page"
date: 2020-03-19T10:06:32Z
menu:
MAIN-MENU-FOR-VERSION:
parent: SUBMENU-FOR-THIS-PAGE-OR-REMOVE-menu-COMPLETELY
tags:
- this
- that
- the other
---
This is a new docs pageThe menu keys are described in menu usage. If the page does not need to appear in the left-hand menu, you can delete the menu section.
The minimum requirement for a page is simply the title and the date.
The MAIN-MENU-FOR-VERSION has to be unique, and is by convention, the project folder name, e.g. corda-os, and the version, e.g. 4.4 contatenated and then all . are replaced with - to give corda-os-4-4.
We are using a renderer that follows the CommonMark Spec
We recommend that you use Visual Studio Code or an editor of your choice that can edit (and preview) Markdown
We also recommend installing markdownlint VSC extension which includes a library of rules to encourage standards and consistency for Markdown files.
In common with most static site generators, content pages begin with a front-matter section.
---
title: "Welcome"
date: 2020-01-08T09:59:25Z
---This can be written in TOML (+++), YAML (---), or JSON { ... }.
We have chosen to primarily use YAML for the front matter format as GitHub knows how to render this.
Shortcodes allow us to extend Markdown.
Note: if you run hugo serve and edit code with shortcodes, occasionally hugo might stop working and you will need to restart it.
We provide note, warning, attention, and tip to highlight blocks of code, for example
{{% warning %}}
this is a warning
{{% /warning %}}Since we provide code snippets for both Java and Kotlin we provide some shortcodes for working with tabbed code.
In the outer scope, always provide a unique tab id (which is used as a page anchor).
Simply surround your back-ticked code blocks with:
{{< tabs name="tabs-1234" >}}
{{% tab name="kotlin" %}}
'''kotlin
//your code here
'''
{{% /tab %}}
{{% tab name="java" %}}
'''java
//your other code here
'''{{% /tab %}}
{{< /tabs >}}To enable MathJax in a page, simply add:
{{% mathjax %}}somewhere in the page, once. And that's it.
To add a Mermaid chart, simply wrap the chart in the following shortcode:
{{% mermaid %}}
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
{{% /mermaid %}}- Index pages should be
_index.mdotherwise sub-pages don't get rendered. - When searching, prefer
gohugoas your search term.
Windows:
.\serve_and_edit.ps1Mac/Linux:
make local-serve-and-edit # or hugo-serve-and-editYou need to install the open package.
If this is your preferred editor, then consider setting HUGO_PARAMS_EDITOR in your environment.
Windows Powershell:
$env:HUGO_PARAMS_EDITOR="atom"
.\serve_and_edit.ps1Mac/Linux:
export HUGO_PARAMS_EDITOR=atom
make local-serve-and-edit # or hugo-serve-and-edit