Skip to main content

Style Guide

You can write content using GitHub-flavored Markdown syntax. Markdown is a way to style text on the web. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like # or *.

Markdown Examples

This page will help you learn about the Markdown used in the Cardano Developer Portal, but the list is not intended to be exhaustive. Read the docusaurus Markdown features for more examples.

Let's start with the basics:

Emphasis, aka italics, with *asterisks* 
or _underscores_.

Strong emphasis, aka bold, with **asterisks**
or __underscores__.

Combined emphasis with **asterisks and _underscores_**.

Strikethrough uses two tildes. ~~Scratch this.~~

You can even [link to the Forum!](https://forum.cardano.org)

Emphasis, aka italics, with asterisks or underscores.

Strong emphasis, aka bold, with asterisks or underscores.

Combined emphasis with asterisks and underscores.

Strikethrough uses two tildes. Scratch this.

You can even link to the Forum!


Code

In the developer portal, you will often have to display code. You can display code with different syntax highlighting:

```javascript
var s = 'JavaScript syntax highlighting';
alert(s);
```
var s = 'JavaScript syntax highlighting';
alert(s);

Tabs

You can use tabs to display code examples in different languages. For example:

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

<Tabs
defaultValue="js"
values={[
{label: 'JavaScript', value: 'js'},
{label: 'PHP', value: 'php'},
{label: 'Python', value: 'py'},
]}>
<TabItem value="js">

```js
function helloWorld() {
console.log('Hello, world!');
}
```

</TabItem>
<TabItem value="php">

```php
<?php echo '<p>Hello, world!</p>'; ?>
```

</TabItem>
<TabItem value="py">

```py
def hello_world():
print 'Hello, world!'
```

</TabItem>
</Tabs>
function helloWorld() {
console.log('Hello, world!');
}
note

Note that the empty lines above and below each language block (in the *md file) is intentional.


Synching tab choices

You can also switch multiple tabs at the same time based on user input:

<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
{label: 'Linux', value: 'linux'},
]
}>
<TabItem value="win">Use Ctrl + C to copy.</TabItem>
<TabItem value="mac">Use Command + C to copy.</TabItem>
<TabItem value="linux">Use Ctrl + C to copy.</TabItem>
</Tabs>

<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
{label: 'Linux', value: 'linux'},
]
}>
<TabItem value="win">Use Ctrl + V to paste.</TabItem>
<TabItem value="mac">Use Command + V to paste.</TabItem>
<TabItem value="linux">Use Ctrl + V to paste.</TabItem>
</Tabs>
Use Ctrl + C to copy.
Use Ctrl + V to paste.

Video embedding

Use this code to embed YouTube videos:

<iframe width="100%" height="325" src="https://www.youtube.com/embed/U92Ks8rucDQ" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture fullscreen"></iframe>

Tables

Colons can be used to align columns:

| Tables        |      Are      |   Cool |
| ------------- | :-----------: | -----: |
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |
TablesAreCool
col 3 isright-aligned$1600
col 2 iscentered$12
zebra stripesare neat$1

There must be at least 3 dashes separating each header cell. The outer pipes (|) are optional, and you don't need to make the raw Markdown line up prettily. You can also use inline Markdown.

| Markdown | Less      | Pretty     |
| -------- | --------- | ---------- |
| _Still_ | `renders` | **nicely** |
| 1 | 2 | 3 |
MarkdownLessPretty
Stillrendersnicely
123

Inline HTML

Inline HTML is basically possible, but should be avoided for various reasons.

<dl>
<dt>Definition list</dt>
<dd>Is something people use sometimes.</dd>

<dt>Markdown in HTML</dt>
<dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
</dl>
Definition list
Is something people use sometimes.
Markdown in HTML
Does *not* work **very** well. Use HTML tags.

Line Breaks

Here's a line for us to start with.

This line is separated from the one above by two newlines, so it will be a _separate paragraph_.
This line is a separate line in the _same paragraph_, created either by two blank spaces or explicit <br /> tag at the end of the previous line.

Here's a line for us to start with.

This line is separated from the one above by two newlines, so it will be a separate paragraph.
This line is a separate line in the same paragraph, created either by two blank spaces or explicit <br /> tag at the end of the previous line.


Admonitions

These different admonitions are available to you. As a general rule: don't overdo it and avoid using admonitions in a row.

:::warning

This is a warning

:::
danger

This is a warning

Please try to avoid other style elements, and always keep in mind that people with visual handicaps should also be able to cope with your content.

Editor extensions and configurations

Last but not least, let's talk about editors, extensions and configurations.

You can use any text editor you like to write Markdown. Visual Studio Code, Sublime, Atom, etc. have plugins that help you adhere to style guides by displaying warnings if you break the rules.

Below are some extensions for these editors that help you write clean guides for the developer portal.

markdownlint

Adds syntax highligting for Markdown files and display configurable warnings for invalid formatting.

  • Install the extension via Command Palette (Ctrl+P) using ext install DavidAnson.vscode-markdownlint

  • Add a .markdownlint.json file to your project with the following configuration.

{
"line-length": false,
"MD004" : false,
"MD033":{
"allowed_elements": ["TabItem", "br", "iframe", "dl", "dt","dd", "em"]
},
"MD034" : false,
"MD046" : false
}

markdowntables

Helps you work with tables

  • Install the extension via Command Palette (Ctrl+P) using ext install pharndt.vscode-markdown-table
Keybindings
Ctrl+Q Ctrl+Fformat table under cursor.
Ctrl+Q Spaceclear cell under cursor.
Ctrl+Q Ctrl+Qtoggle table mode
  • In table mode
Keybindings
Tabnavigate to the next cell in table
Shift+Tabnavigate to the previous cell in table
Alt+Numpad +Create new column left to the current position
Alt+Numpad -delete current column

rest-book

When you write guides for cardano-wallet or other components with an API, you might want to include the response for a certain request in your guide. It can be useful not to leave the environment of your editor as to not lose focus or get distracted. rest-book allows you to execute HTTP requests within your editor.

  • Install the extension via Command Palette (Ctrl+P) using ext install tanhakabir.rest-book
  • Open or create a .restbook file to use the extension.

Editorial Style Guide

To make everything consistent we should agree on spellings and terms here.

Spelling/TermComment
adaWhen talking about the cryptocurrency, do not capitalize, unless at the beginning of a sentence. The idea behind this is to treat it like dollars or euros. If you are in doubt, in English, prefer ada over ADA. Capitalised ADA stands for the ticker symbol only.
ADAThe ticker symbol for ada, like EUR or USD.
tAdaTest ada is tAda, not tADA or TADA. See ada.
BashoThe fourth era of the Cardano development focused on performance. Named after Matsuo Basho, a Japanese poet and the master of haiku.
ByronFirst era in Cardano development. Named after the Romantic poet who was the father of Ada Lovelace.
the Cardano FoundationAlways use the Cardano Foundation.
DAppNote the capitalization: Decentralized Application.
dcSparkCreators of Flint Wallet and Milkomeda. Capitalized S, everything else lower case.
DRepNote the capitalization: Delegated Representative. DRep as an abbreviation for Delegated Representative follows standard practices for abbreviations in English: taking the first letter of each word. This makes it intuitive and clear in most contexts. It is also in line with the DApp abbreviation. In crypto, the lowercase “d“ is often used to signify “decentralized,” as in dApp (decentralized application) or dGov (decentralized governance). Using “dRep” might imply “decentralized representative”.
EMURGOAll caps in line with EMURGO’s branding.
the FoundationInterchangeable with the Cardano Foundation, the is not capitalized, but Foundation should be.
GitHubNote the capitalized H.
GoguenThe third era of the Cardano development focused on smart contracts. Named in honour of Joseph Goguen, an US computer scientist.
hard forkTwo words.
IOHKIOHK is now IOG.
IOGIOG was IOHK.
MainnetOne word. Capitalise when it's a noun (the Mainnet) but not when it's an adjective (mainnet functionality), qualified by another proper name (the Cardano mainnet), or used as a symbol (e.g. enable Marlowe on mainnet).
OuroborosOuroboros is a family of Cardano's consensus protocols. There are different flavors: Classic, Praos, Genesis, Chronos
sidechainsOne word.
stake poolTwo words.
stakingTry to avoid term staking without context as it is ambiguous. staking refers to the whole process of both delegating and setting up a pool but many people confuse this with the actual process of creating blocks. delegating means that people delegate their stake to a stake pool.
StricaCreators of Typhon Wallet, Cardanoscan and Flac Finance. Capitalized S, everything else lower case.
proof of stakeLower case. Hyphenate when followed by a noun: proof-of-stake systems.
proof of workLower case. Hyphenate when followed by a noun: proof-of-work systems.
TestnetOne word. Capitalise when it's a particular testnet (e.g. Preview testnet) but not when it's an adjective (e.g. testnet functionality) or referring to more than one (e.g. new iterations of the testnets).
use caseNot use-case.
VoltaireThe fifth era of the Cardano development focused on governance and treasury. Named after the French philosopher who prized criticism and argued for the separation of church and state.
white paperTwo words.