Versions Compared

Old Version 2

changes.mady.by.user Felipe Faraggi

Saved on

compared with

New Version 3

changes.mady.by.user Felipe Faraggi

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • 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.

...

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.

...

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 locally before pushing your changes within a pull-request. As the final documentation is build with MkDocs, you have to build your docs locally with this tool to ensure the Markdown is correctly understood and displayed.

...

Important: Run python --version to make sure you are using version indicated in readthedocs.yml file. If you are updating from a previous Python version you will also have to run pip3 install again and check your path.

Formatting Markdown For Doc Site

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

...

  • 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.

...

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.

...

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
    This example shows how to use the `net_listening` RPC method.

    ```bash tab="curl HTTP request"
    $ curl -X POST --data '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":53}' <JSON-RPC-http-endpoint:port>
    ```

    ```bash tab="wscat WS request"
    {"jsonrpc":"2.0","method":"net_listening","params":[],"id":53}
    ```

    ```json tab="JSON result"
    {
    "jsonrpc" : "2.0",
    "id" : 53,
    "result" : true
    }
    ```

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.

...

description: This is an example page
<!--- END of page meta data -->

*[PoA]: Proof of Work

Clique is a PoA mechanism used in the Rinkeby test network

Math

Arithmatex extension enables writing math formulas in the documentation using the provided syntax.

...

$\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.

...

???+ 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 ⚠️

...

Example: :warning: displays ⚠️

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.

...

==This is highlighted text==

Strike Through

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

...

~~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.

Code Samples And Examples With SuperFences

Format The Code

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

Including Code in the Documentation

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

...

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

Tabbed Code Blocks

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

...

```bash tab="Syntax"
$ besu rlp encode [--from=<FILE>] [--to=<FILE>] [--type=<type>]
```

```bash tab="File Example"
$ besu rlp encode --from=ibft_extra_data.json --to=extra_data_for_ibft_genesis.txt --type=IBFT_EXTRA_DATA
```

```bash tab="Standard Input/Output Example"
$ cat extra_data.json | besu rlp encode > rlp.txt
```

#### Line Numbers On Long Code Samples

[SuperFences] can also add [line numbers](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#showing-line-numbers)
to the code sample which makes it easier when discussing the code the sample.

The line numbers will only appear on the code block that uses the `linenums="1"` parameter.

Example:
````markdown
    ```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.

...