Skip to main content

Format Markdown

Guidelines for formatting Markdown help writers and reviewers navigate the documentation source code and review changes. They also ensure that Markdown features render properly on the doc site.

Refer to the following guidelines when formatting Markdown in Consensys docs.

note

The Markdown syntax for admonitions and tabs is specific to Docusaurus. See the Docusaurus Markdown documentation for more information on using Markdown features specific to Docusaurus.

File names​

The name of each documentation folder and Markdown file must contain only lowercase letters and dashes (-) to represent spaces. Use simple file names that match the page titles and that make sense with the entire file path. For example:

how-to/
├─ get-started.md
├─ manage-keys.md
├─ request-permissions.md
├─ troubleshoot.md
concepts/
├─ architecture.md
├─ lifecycle.md
├─ execution-environment.md
...

Metadata​

You can configure metadata for each doc page using Markdown front matter at the top of the page. For example:

---
title: Use MetaMask SDK with React
sidebar_label: React
sidebar_position: 2
description: Import MetaMask SDK into your React dapp.
max_toc_heading_level: 3
---

You should provide at least a clear description for each page using front matter.

Column limit​

Each Markdown line should be (roughly) limited to 100 columns long to be readable on any editor. For example:

In this example, this first sentence exceeds 100 characters, so we recommend wrapping it into
multiple lines.
One line break displays as a space, so this Markdown renders as one paragraph without line breaks.
We also recommend starting each new sentence on a new line, even if the previous line didn't reach
100 columns, for easy reviewing.
You can set a [vertical ruler](https://dev.to/brad_beggs/vs-code-vertical-rulers-for-prettier-code-3gp3)
in your text editor as a heuristic.

Tables​

Format tables to be readable in the source code. Add an appropriate number of spaces to align the columns in the source code. For example, do this:

| Syntax    | Description |
|-----------|-------------|
| Name      | Title       |
| Paragraph | Text        |

Not this:

| Syntax | Description |
|--|--|
| Name | Title |
| Paragraph | Text |

You can quickly format tables using Markdown Table Formatter or create tables from scratch using Tables Generator. Some editors also have settings or plugins to auto-format Markdown tables.

Admonitions​

Use admonitions to include side content or highlight important content. For example:

:::caution[important]
`eth_sign` is deprecated.
:::

:::note
MetaMask supports signing transactions using Trezor and Ledger hardware wallets.
These wallets only support signing data using `personal_sign`.
If you can't log in to a dapp when using a Ledger or Trezor, the dapp might be requesting you to
sign data using an unsupported method, in which case we recommend using your standard MetaMask account.
:::

Code samples​

Use code blocks to present code samples.

A basic code block uses triple back ticks (`) and the language name to enable syntax highlighting. For example:

```javascript
if (typeof window.ethereum !== "undefined") {
  console.log("MetaMask is installed!");
}
```

Code sample style guide​

Make sure to provide developer-friendly code samples. The following are some rules used throughout the Consensys docs:

  • Use double quotes (") instead of single quotes (').
  • Indent lines using two spaces instead of four.
  • Write code samples that can be easily copied and pasted, and work as expected.
  • Follow the style guide of the programming language used in the code sample.
example

❌ To start Teku, run the following command:

// Set --ee-endpoint to the URL of your execution engine and
// --ee-jwt-secret-file to the path to your JWT secret file.
user@mycomputer Develop % teku --ee-endpoint=http://localhost:8550 --ee-jwt-secret-file=my-jwt-secret.hex --metrics-enabled=true --rest-api-enabled=true

✅ To start Teku, run the following command:

teku \
  --ee-endpoint=<URL of execution engine>        \
  --ee-jwt-secret-file=<path to JWT secret file> \
  --metrics-enabled=true                         \
  --rest-api-enabled=true

See the Microsoft Writing Style Guide for more guidelines for writing code examples.

Tabs​

Use tabs to display certain content, such as code samples in different languages. For example:

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

<Tabs>
<TabItem value="HTML">

```html
<!-- HTML code block -->
```

</TabItem>
<TabItem value="JavaScript">

```javascript
// JavaScript code block
```

</TabItem>
<TabItem value="Markdown">

```markdown
- This is an example Markdown list.
- This is **bold** and *italicized* text.
```

</TabItem>
</Tabs>

This renders as the following:

<!-- HTML code block -->