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:
- Text
- Headers
- Links
- Quotes
- Images
- Lists
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!
#Level 1
headings are rendered automatically from the title
property of your frontmatter
.
Therefore use ## Level 2
headings as the top most heading in the docs.
---
id: front-matter
title: I am the frontmatter
description: Always include the frontmatter in your documents
---
## Structured documents
As a rule, it is useful to have different levels
of headings to structure your documents. Start rows
with a `##` to create headings. Several `#` in a row
indicate smaller heading sizes.
### This is a level 3 heading
#### This is a level 4 heading
You can use up to `######` six for different heading sizes.
I am the frontmatter
Structured documents
As a rule, it is useful to have different levels of headings to structure your documents. Start rows with a #
to create headings. Several ##
in a row indicate smaller heading sizes.
This is a level 3 heading
This is a level 4 heading
You can use up to ######
six for different heading sizes.
[I'm an inline-style link](https://forum.cardano.org)
[I'm an inline-style link with title](https://forum.cardano.org "Cardano Forum")
[I'm a reference-style link][arbitrary case-insensitive reference text]
[You can use numbers for reference-style link definitions][1]
Or leave it empty and use the [link text itself].
URLs and URLs in angle brackets will automatically get turned into links. http://www.cardano.org or <http://www.cardano.org>.
Some text to show that the reference links can follow later.
[arbitrary case-insensitive reference text]: https://www.cardano.org
[1]: https://forum.cardano.org
[link text itself]: https://www.cardano.org
I'm an inline-style link with title
You can use numbers for reference-style link definitions
Or leave it empty and use the link text itself.
URLs will automatically get turned into links. Example: https://www.cardano.org
Some text to show that the reference links can follow later.
If you'd like to quote someone, use the > character
before the line:
> It’s not about who’s first to market or how quickly
we can upgrade something. It’s about what’s fit for
purpose. - **Charles Hoskinson**
If you'd like to quote someone, use the > character before the line:
It’s not about who’s first to market or how quickly we can upgrade something. It’s about what’s fit for purpose. - Charles Hoskinson
Here's is the Plutus logo (hover to see the title text):
Inline-style: ![alt text](../static/img/logo-plutus-small.png 'This is the Plutus logo inline-style')
Reference-style: ![alt text][logo]
[logo]: https://raw.githubusercontent.com/adam-p/markdown-here/master/src/common/images/icon48.png 'This is a logo reference-style'
Images from any folder can be used by providing path to file. Path should be relative to Markdown file:
![alt text](../static/img/logo-plutus.png)
Here's is the Plutus logo (hover to see the title text): Inline-style:
Reference-style: ![alt text][logo] [logo]: https://raw.githubusercontent.com/adam-p/markdown-here/master/src/common/images/icon48.png 'This is a logo reference-style'
Images from any folder can be used by providing path to file. Path should be relative to Markdown file:
1. First ordered list item
2. Another item
- Unordered sub-list.
3. Actual numbers don't matter, just that it's a number
1. Ordered sub-list
4. And another item.
* Unordered list can use asterisks
- Or minuses
+ Or pluses
- First ordered list item
- Another item
- Unordered sub-list.
- Actual numbers don't matter, just that it's a number
- Ordered sub-list
- And another item.
- Unordered list can use asterisks
- Or minuses
- Or pluses
Code
In the developer portal, you will often have to display code. You can display code with different syntax highlighting:
- JavaScript
- Python
- C#
- JSON
- Shell
- Text
- Extras
var s = 'JavaScript syntax highlighting';
alert(s);
var s = 'JavaScript syntax highlighting';
alert(s);
s = "Python syntax highlighting"
print(s)
s = "Python syntax highlighting"
print(s)
using System;
var s = "c# syntax highlighting";
Console.WriteLine(s);
using System;
var s = "c# syntax highlighting";
Console.WriteLine(s);
{
"json_number": 225,
"json_boolean": true,
"json_string": "JSON syntax highlighting"
}
{
"json_number": 225,
"json_boolean": true,
"json_string": "JSON syntax highlighting"
}
ls
echo "Shell syntax highlighting"
sudo dmesg
top
ls
echo "Shell syntax highlighting"
sudo dmesg
top
No language indicated, so no syntax highlighting.
But let's throw in a <b>tag</b>.
No language indicated, so no syntax highlighting.
But let's throw in a <b>tag</b>.
function highlightMe() {
console.log('This line can be highlighted!');
console.log('You can also highlight multiple lines');
}
function highlightMe() {
console.log('This line can be highlighted!');
console.log('You can also highlight multiple lines');
}
You can add a title to the code block by adding title
key after the language (leave a space between them).
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}
Tabs
You can use tabs to display code examples in different languages. For example:
html import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
- JavaScript
- PHP
- Python
function helloWorld() {
console.log('Hello, world!');
}
<?php echo '<p>Hello, world!</p>'; ?>
def hello_world():
print 'Hello, world!'
- JavaScript
- PHP
- Python
function helloWorld() {
console.log('Hello, world!');
}
<?php echo '<p>Hello, world!</p>'; ?>
def hello_world():
print 'Hello, world!'
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>
- Windows
- macOS
- Linux
- Windows
- macOS
- Linux
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 |
Tables | Are | Cool |
---|---|---|
col 3 is | right-aligned | $1600 |
col 2 is | centered | $12 |
zebra stripes | are 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 |
Markdown | Less | Pretty |
---|---|---|
Still | renders | nicely |
1 | 2 | 3 |
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.
- Note
- Tip
- Important
- Caution
- Warning
- Custom
:::note
This is a note
:::
This is a note
:::tip
This is a tip
:::
This is a tip
:::important
This is important
:::
This is important
:::caution
This is a caution
:::
This is a caution
:::warning
This is a warning
:::
This is a warning
:::tip[Custom Title]
This is a tip admonition with a custom title
:::
This is a tip admonition with a custom title
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.
- Visual Studio Code
- Sublime
-
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
}
- Install SublimeLinter as described here
- Install Node.js
- Install
markdownlint
by usingnpm install -g markdownlint-cli
- Within Sublime Text's Command Palette (Ctrl+Shift+P) type
install
and selectPackage Control: Install Package
. - When the plug-in list appears, type
markdownlint
and selectSublimeLinter-contrib-markdownlint
.
- Add a
.markdownlintrc
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
- Visual Studio Code
- Install the extension via Command Palette (Ctrl+P) using
ext install pharndt.vscode-markdown-table
Keybindings | |
---|---|
Ctrl+Q Ctrl+F | format table under cursor. |
Ctrl+Q Space | clear cell under cursor. |
Ctrl+Q Ctrl+Q | toggle table mode |
- In table mode
Keybindings | |
---|---|
Tab | navigate to the next cell in table |
Shift+Tab | navigate 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.
- Visual Studio Code
- 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/Term | Comment |
---|---|
ada | When 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. |
ADA | The ticker symbol for ada, like EUR or USD. |
tAda | Test ada is tAda, not tADA or TADA. See ada . |
Basho | The fourth era of the Cardano development focused on performance. Named after Matsuo Basho, a Japanese poet and the master of haiku. |
Byron | First era in Cardano development. Named after the Romantic poet who was the father of Ada Lovelace. |
the Cardano Foundation | Always use the Cardano Foundation. |
DApp | Note the capitalization: Decentralized Application. |
dcSpark | Creators of Flint Wallet and Milkomeda. Capitalized S, everything else lower case. |
DRep | Note 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”. |
EMURGO | All caps in line with EMURGO’s branding. |
the Foundation | Interchangeable with the Cardano Foundation , the is not capitalized, but Foundation should be. |
GitHub | Note the capitalized H. |
Goguen | The third era of the Cardano development focused on smart contracts. Named in honour of Joseph Goguen, an US computer scientist. |
hard fork | Two words. |
IOHK | IOHK is now IOG. |
IOG | IOG was IOHK. |
Mainnet | One 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 ). |
Ouroboros | Ouroboros is a family of Cardano's consensus protocols. There are different flavors: Classic, Praos, Genesis, Chronos |
sidechains | One word. |
stake pool | Two words. |
staking | Try 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. |
Strica | Creators of Typhon Wallet, Cardanoscan and Flac Finance. Capitalized S, everything else lower case. |
proof of stake | Lower case. Hyphenate when followed by a noun: proof-of-stake systems. |
proof of work | Lower case. Hyphenate when followed by a noun: proof-of-work systems. |
Testnet | One 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 case | Not use-case. |
Voltaire | The 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 paper | Two words. |