Hyperledger Besu documentation is written using Markdown syntax.

However, we use two flavors of this syntax:

• One for pages inside the /docs directory that will be rendered by MkDocs as described below in the Installed Markdown Extensions section.
• Another using the Github syntax for pages outside of this documentation directory. These are mainly files to support our open source community.

MkDocs Documentation Website

The Hyperledger Besu documentation website is built from the content of the /docs directory.

/docs Directory

The /docs directory in the Hyperledger Besu documentation repository contains all the documentation that is generated into a static HTML website using MkDocs and the Mkdocs Material theme and hosted by readthedocs.org.

The documentation is automatically updated using WebHooks linking GitHub to the readthedocs.org site when you merge a pull-request in the main branch of Hyperledger Besu documentation.

The system also detects tags in the Github repository and takes care of making the latest stable release and previous versions available.

If any issues occur, contact the maintainers of the Hyperledger Besu documentation project.

MkDocs Configuration

MkDocs is a Python tool that generates the static HTML website that is published.

Our MkDocs setup uses a Mkdocs Material theme to render the html pages. It also comes with a number of useful extensions.

MkDocs is configured in the mdkocs.yml file.

This file configures:

• Site meta data and variables
• Theme configuration
• Page navigation
• Extensions
• Plugins

If you add pages to the documentation (rather than updating existing pages), update the "nav" section to add your page and specify the page name.

Preview The Documentation

We recommended previewing your work before it's merged. There's two options, building locally using Python virtual environments or previewing using ReadTheDocs PR preview.

As the final documentation is build with MkDocs, you building your docs locally or on ReadTheDocs PR preview with this tool ensures the Markdown is correctly understood and displayed.

Preview with ReadTheDocs

When creating a PR on the doc repository, checks will trigger to verify links, markdown syntax, writing style and some more. It will also build the doc on ReadTheDocs as a PR preview.

You can find the link to this preview in the check list at the bottom of your PR page as shown on the following screenshot:

Image Removed

Preview Locally

Check locally before pushing your changes within a pull-request.

To preview Hyperledger Besu documentation locally:

• Install Python 3
• Create a virtual environment for the project running:

  python3 -m venv env

  this will add an env dir in your project. Never commit it, it should be ignored by git but if not, ignore it and commit the changes in the .gitignore file.
• Activate the virtual environment: source env/bin/activate
  Notice the (env) at the beginning of your prompt now, you activated the virtual environment.
• Install all the required dependencies in this virtual environment: pip install -r CI/requirements.txt
• Run the following command in the project directory: mkdocs serve
• Follow the link displayed on the output of this command that looks like [I 190206 18:48:47 server:298] Serving on http://127.0.0.1:8000, here connect to http://127.0.0.1:8000
  You can let this doc server run while you work on the doc, it updates the local website automatically when you save changes in your Markdown files.

Note: Deactivate the virtual environment if you work on another Python project. To do so, run: deactivate
See Python 3 virtual environment doc for more details.  

Important: To check that mkdocs is using the correct python version, run head $(which mkdocs) to get the path to the python executable, then /path/to/python --version  which should match what is specified in readthedocs.yml  in the project directory

Formatting Markdown For Doc Site

Final documentation rendering is essential, but the format of the Markdown files is also very important.

Formatting the Markdown code helps reviewers and writers easily navigate in the code and review your changes.

A few basic rules:

• Each file must contain a header composed of meta-data and ended by a specific comment. Ex:

title: Installation overview
description: Overview and requirements to install Hyperledger Besu
<!--- END of page meta data -->

• As for other code, each line of Markdown code must be limited to 100 columns long to be readable on any editor. Lines have to be wrapped without cutting the line in the middle of a word. A line break displays as a space.
• No HTML markup can be used inside a Markdown document. We provide a lot of extensions that are able to do the same thing without HTML. If you think one is missing, just discuss it with the team on Besu chat and we'll decide together if it's worth adding an extension.
• Only one first level title can be present on a page.
• Format tables so they are also readable in the source code. You can quickly achieve this by using a tool like http://markdowntable.com/

Installed Markdown Extensions

Important: Extensions are only available for the docs under /docs directory.

As markdown can be a bit limited when it comes to some specific rendering of code, TOCs, and other documentation elements, we configured some extensions for these items. Extensions enable you to use simple Markdown syntax to achieve some complex rendering.

Important: Never use HTML tags directly in the Markdown files to try to render content. For consistency reasons we only allow the specific renderings available in the extensions.

Here is a list of the available extensions:

TOC

This extension automatically displays a table of content of the current page on the right side of the page. It displays titles to the third level (###). After the third level, titles won't be displayed in the TOC.

This extension also displays a link on the right of any title called "permalink". This link can be used to point directly to the title from another website.

Include

If you have content to be repeated on multiple pages, you can create it in a common page in and include it in all required pages.

Example: To include the content of the "test_accounts.md" page in the "/docs/global" directory in another page, use:

{!global/test_accounts.md!}

Important: An exclude plugin is installed (see mkdocs.yml file for the config of exclusions). It excludes pages from the final rendered site as otherwise every .md file is rendered and copied. Pages will still be in the source repository but they won't be copied in the final site and won't appear in the search results even if you did not link them from the navigation. It's handy to prevent include files to be reachable as standalone pages as they are intended to be included in other pages.

Admonition

The Admonition extension enables information, warning, and danger blocks.

Example:

!!! note
    This is a multi line note
    in the Hyperledger Besu documentation. 

The 4 spaces indentation is required for the content to be part of the admonition.

We generally use the following types in our documentation:

...

Extensions allow you to use simple Markdown syntax to achieve complex rendering. The following are the available extensions for Besu documentation.

Important: Extensions are only available for the Markdown files under the docs directory.

Abbreviations¶

We recommend avoiding the use of abbreviations, but some such as “PoW” for “proof of work” or “dapp” for “decentralized application” have become part of the Ethereum jargon. The Abbreviations extension enables defining abbreviations, so that the full form displays when you hover over the abbreviation.

Define abbreviations at the end of the Markdown file.

Example:

---
description: This is an example page
---

# My example This page explains PoA networks.

... more text ...

*[PoA]: proof of authority

Call-outs¶

The Admonition extension enables call-out blocks. These are used frequently in the ConsenSys documentation to include side content or highlight important content.

Begin each call-out with three exclamation points and the call-out type. You can change the call-out title by adding it in quotes.

Example:

!!! note

    This is a multi-line note in the ConsenSys documentation.
    You can replace `note` with a different call-out type.
    The default note title is `Note`.
    Each line in the call-out content must be indented by four spaces to be included in the call-out.

Supported types include:

• Note: Used to add information about a subject that

...

• doesn’t always need to be taken

...

• into account. For example, “When running on localhost, include 127.0.0.1 as a listed IP address.”

• Important: Used to add important information about a subject that should always be taken into account. For example, “Allow Docker up to 6G of memory.”

• Example: Used to display an example. This is often used with a code sample.

• Info: Used to add non-essential detail about a subject. For example, “The miner coinbase account is one of the accounts defined in the genesis file.

...

• ”

• Tip

...

• : Used to

...

• add information that could help improve the use of

...

• a tool

...

• . For example, “To restart the private network in the future, start from

...

• step 4.”

• Caution: Used to warn the users to proceed with caution. For example, “Configuring alternative elliptic curves is an experimental feature.”

• Warning: Used to warn the users about something important.

...

• For example, “This will be deprecated in the next version.

...

• ”

...

• Critical: Used to alert the user about a potential dangerous effect such as a risk of destroying something or losing assets.

...

• For example, “Never use the development private keys for production use.”

Collapsible call-outs¶

The Details extension enables collapsible call-outs by replacing the exclamation points with question marks. The call-out can be open or collapsed by default. This helps reduce the content length and enables a faster overview of the whole page.

Example:

???+ note "Collapsible note"

    This is a collapsible note.

...

    The plus sign makes it open by default.
    Remove the plus sign and it will be collapsed by default.

Checklists¶

The Tasklist extension enables displaying an unordered list as a checklist.

Example:

- [ ] This list item has an unchecked checkbox.
- [x] This list item has a checked checkbox.

Code samples¶

The SuperFences extension enables using code blocks to present code samples in the documentation. A basic code block uses triple back ticks (`) and the language name to enable syntax highlighting. Always surround code blocks with blank lines.

Example:

```json
{
  "jsonrpc": "2.0",
  "

...

id":

...

Footnotes

The Footnotes extension enables adding footnotes.

Footnotes display content at the end of the page and a numbered link inside the text to go to this content. The extension also adds a link at the end of the footnote back to the text.

Definitions List

The def_list extension enables listing definitions directly in the Markdown.

Abbreviations

Generally we avoid the use of abbreviations but some like "PoW" for proof-of-work or "dApp" for decentralized application are now part of the Ethereum jargon. The Abbreviation extension enables a tool tip hint to be provided for abbreviations.

Place abbreviations at the beginning of the Markdown file just after the meta-data header.

Example:

...

Math

...

1,
  "result": true
}
```

Tabbed code blocks¶

SuperFences also enables tabbed code blocks. The following example groups usage syntax and an example in different tabs in the same block.

Example:

=== "Syntax"

    ```bash
    ethsigner --chain-id=<chainId>
    ```

=== "Example"

    ```bash
    ethsigner --chain-id=1337
    ```

Line numbers¶

SuperFences also enables adding line numbers to long code samples, which makes it easier when discussing the sample. The line numbers only appear in a code block that uses the linenums="1" parameter.

Example:

```javascript linenums="1"
const Web3 = require("web3");
const Web3Quorum = require("web3js-quorum");
const web3 = new Web3Quorum(new Web3("http://localhost:22000"));
web3.priv.generateAndSendRawTransaction(options);
```

Code syntax highlight¶

The Highlight extension enables automatic syntax highlighting of code blocks. Define the code language after the code block delimiter to ensure correct highlighting. If you don’t provide the language name, the extension attempts to automatically discover it, but this can lead to errors.

Example:

```json
{
  "jsonrpc" : "2.0",
  "id" : 51,
  "result" : {
    "startingBlock" : "0x5a0",
    "currentBlock" : "0xad9",
    "highestBlock" : "0xad9"
  }
}
```

Refer to the full list of support languages.

Definitions¶

The Definition List extension enables listing definitions. This may be useful for creating glossaries.

Example:

Consensus layer
:   The layer of the Ethereum network that enforces network rules, and generates and verifies blocks.
    Previously known as "Ethereum 2.0" or "Eth2."

Execution layer
:   The layer of the Ethereum network that contains and executes smart contracts.
    Previously known as "Ethereum 1.0" or "Eth1."

Emojis¶

You can use emojis in the Markdown. Emojis are fun, but they can also be useful to draw the user’s attention. Use only neutral emojis such as :warning:, which displays Image Added.

Refer to the full list of available emojis.

Footnotes¶

The Footnotes extension enables adding footnotes at the end of a page.

Example:

---
description: This is an example page
---

# My example

You can add a footnote[^1] to provide additional information about a subject.
The footnote number displays as a clickable superscript that takes the user to the footnote.

... more text ...

[^1]: The footnote goes here.
    A clickable arrow displays that takes the user back to the original text.
    When writing multi-line footnotes, indent each line with four spaces.

Global content¶

If you have content to be repeated on multiple pages, you can create it in a common page in the /docs/global directory and include it in all required pages.

For example, use {!global/test_accounts.md!} to include the content of the test_accounts.md page in another page.

Info

The exclude plugin excludes pages in the /docs/global directory (configurable in mkdocs.yml) from the final rendered site, since otherwise, every Markdown file is rendered and copied. It’s useful to prevent global files to be reachable as standalone pages, since they’re intended to be included in other pages.

Excluded pages are still in the source repository, but they aren’t copied in the final site and don’t appear in the search results.

Highlight¶

The Mark extension enables highlighting of text. Text surrounded by double equal signs is highlighted in yellow.

Example:

==This is highlighted text==

Key presses¶

The Keys extension enables styling key presses by surrounding them with double plus signs.

Example:

++ctrl+alt+delete++

Magic links¶

The MagicLink extension automatically displays a URL as a link. You don’t need to surround the URL with Markdown link syntax.

Math¶

The Arithmatex extension enables rendered math formulas in the documentation using MathJax syntax.

Example:

$\sigma=\displaystyle\prod_{k=1}^t\sigma_{i_k}^{L_{i_k}(0)}$

Constructing

...

the

...

threshold

...

signature

...

$\sigma$

...

from

...

$t$

...

individual

...

signatures

...

$\sigma_{i_k}$,

...

$k=1,\dots,t$

...

and

...

the

...

Lagrange

...

polynomials

...

$L_{i_1},

...

\dots,L_{i_t}$

...

associated

...

to

...

the

...

set

...

$I=\{i_1,\dots,i_t\}$

...

of

...

signers.

Better Emphasis

The Betterem extension is automatically applied to your bold and italic content.

Keyboard Shortcuts

The Keys syntax extension enables displaying keyboard shortcuts.

Example:

++ctrl+C++

Folding Details Blocks

You can use a folding block to hide content. The block can be closed by default or open. This pattern helps reduce the content length and enables a faster overview of the whole page.

Ex:

???+ note "Folding details"
    This is the detail of my content.
    The plus sign makes it unfolded by default.
    Remove the plus sign and it will be folded by default.

Emojis

Emojis are fun, but they can also be useful to draw the reader's attention. Try to use only neutral emojis like ⚠️

Refer to a supported full list of available emojis to find the suitable code.

Example: :warning: displays ⚠️

Magic Links

If you want an URL to be displayed as a link, simply write it and this extension automatically displays it as a link. You don't need to surround it with Markdown links syntax.

Highlight Content

The Mark extension enables highlighting of content.

Text surrounded by double equals is highlighted in yellow.

Example:

==This is highlighted text==

Strike Through

The tilde syntax extensions enables text strike through to be displayed.

Example:

~~This is the wrong way to do~~

Symbols

The Smart symbols syntax enables the inclusion of symbols.

Ex: --> will draw a nice right arrow.

Task lists

The Task list syntax extension enables displaying a list as a checklist.

Attributes list

The Attributes list extension enables adding attributes that will be added to the HTML rendering without using HTML directly in the MarkDown syntax.

Code Samples And Examples With SuperFences

Format The Code

For writing code examples inside the documentation, refer to the developer style guides:

• Java : refer to Hyperledger Besu coding convention.
• JSON : use https://jsonformatter.curiousconcept.com/ to format your JSON code.
• TOML : we follow version 0.5.0 language definition.
  JavaScript : see Google JavaScript Style Guide.

Including Code in the Documentation

We use code-blocks provided by the SuperFences extension to present code samples and examples in the documentation.

A basic code-block uses triple back ticks and the language name to enable syntax highlighting.

For example, a JSON result is written as:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}
```

Tabbed Code Blocks

SuperFences enables additional functionality such as the tabbed code-block.

For example, to group the usage syntax and a usage example in the same block with tabs:

...

Line Numbers On Long Code Samples

...

Example:

```javascript linenums="1"
    // A very long javascript sample code
```

Code Syntax Highlight

Codehilite extension enables automatic syntax highlighting of code blocks. Define the language after the code block delimiter to ensure correct highlighting. If you don't provide the language name, the extension attempts to automatically discover it but this can lead to errors.

Example:

```json
{
  "jsonrpc" : "2.0",
  "id" : 51,
  "result" : {
    "startingBlock" : "0x5a0",
    "currentBlock" : "0xad9",
    "highestBlock" : "0xad9"
  }
}
```

...

Plant UML diagrams¶

You can add diagrams using Plant UML syntax.

Example:

```plantuml format="svg" alt="Plantum diagram example" title="My super diagram"
Actor1 -> Actor2: calls
Actor1 <-- Actor2: responds
```

Strikethrough¶

The Tilde extension enables displaying text strikethrough by surrounding the text with double tildes (~).

Example:

~~This text is struck through~~

Symbols¶

The SmartSymbols extension enables symbols. For example, --> displays as →.

TOC¶

The Table of Contents extension automatically displays a table of contents of the current page on the right side of the page. It displays titles to the third level (titles prefixed with ###).

This extension also displays a permalink on the right of any title. This permalink can be used to point directly to the title from another website.

Variables¶

The Extra Variables plugin enables using values from the extra section in mkdocs.yml, or if using the new system, from mkdocs.extra.yml, as variables in the Markdown code.

For example, if you have the following in mkdocs.yml or mkdocs.extra.yml:

extra:
  support:
    email: quorum@consensys.net

You can display the email in any documentation page using:

{{support.email}}