Formatting

This page showcases the various formatting and layout options available for content. This allows editors to better understand their toolbox and access reference code. It also allows designers to see the design system in one place.

The design source file is a public Figma community file you can find here. To improve the design, please start with the Figma file and make a proposal in Slack or Github before implementing.

Text
Headers
Blockquotes
Links
Images
Animations
Gallery
Lists
Tables
Code
YouTube videos
Prototypes
Tips & recommendations
Facts
Do’s and don’ts
Footnotes

Basic markdown formatting

We use Markdown when writing content. Markdown is a plain-text formatting syntax that helps us better prepare our text for the web. Below you can find an overview of commonly used syntax elements.

Text formatting

Text can be bold, italic, or ~~strikethrough~~.

**bold**
_italic_
~~strikethrough~~

There should be whitespace between paragraphs.

Headers

# h1
## h2
### h3
#### h4
##### h5
###### h6

h1 header

h2 header

h3 header

H4 header

h5 header

h6 header

Blockquote

> The details are not the details. They make the design.
>
> <cite>By <a href="https://bitcoin.design">Charles Eames</a></cite>

The details are not the details. They make the design.

By Charles Eames

Links

External Links

[Link to another page](https://bitcoin.org/bitcoin.pdf)

Link to another page

Internal links

[Linking](/guide/getting-started/why-bitcoin-is-unique/)

Linking

Button links

[Filled button link](https://bitcoin.org/bitcoin.pdf){: .button}
[Outline button link](https://bitcoin.org/bitcoin.pdf){: .button.-outline}

Filled button link Outline button link

Images

Let’s start with a very wide image that extends beyond the content width on desktops. Note how a different image is shown on mobile. This can be used to reformat image content to a portrait format.

{% include picture.html
   image = "/assets/images/guide/contribute/formatting/example-image-wide-desktop.jpg"
   retina = "/assets/images/guide/contribute/formatting/example-image-wide-desktop@2x.jpg"
   mobile = "/assets/images/guide/contribute/formatting/example-image-wide-mobile.jpg"
   mobileRetina = "/assets/images/guide/contribute/formatting/example-image-wide-mobile@2x.jpg"
   alt-text = "Example image"
   width = 1600
   height = 800
   layout = "full-width"
%}

Image fits content width

{% include picture.html
   image = "/assets/images/guide/contribute/formatting/example-image-wide-desktop.jpg"
   retina = "/assets/images/guide/contribute/formatting/example-image-wide-desktop@2x.jpg"
   mobile = "/assets/images/guide/contribute/formatting/example-image-wide-mobile.jpg"
   mobileRetina = "/assets/images/guide/contribute/formatting/example-image-wide-mobile@2x.jpg"
   alt-text = "Example image"
   width = 1600
   height = 800
%}

This image can be clicked on to view it in a modal overlay. If the modal image needs to use different dimensions than the main image, this can be defined using the optional modalWidth and modalHeight attributes together.

{% include picture.html
   image = "/assets/images/guide/contribute/formatting/example-image-mobile-screen-modal.png"
   retina = "/assets/images/guide/contribute/formatting/example-image-mobile-screen-modal@2x.png"
   mobile = "/assets/images/guide/contribute/formatting/example-image-mobile-screen-modal.png"
   mobileRetina = "/assets/images/guide/contribute/formatting/example-image-mobile-screen-modal@2x.png"
   modalImage = "/assets/images/guide/contribute/formatting/example-image-mobile-screen-modal@2x.png"
   caption = "This image has some small details, so click on it to see it in a modal window."
   alt-text = "Optional image modal"
   width = 250
   height = 541
   modalWidth = 250
   modalHeight = 541
%}

Optional image modal — This image has some small details, so click on it to see it in a modal window.

Modal image can also have an alternate image defined for mobile devices. This is useful for situations where the mobile image uses a different aspect ratio than the main image. The mobile image’s dimensions can be defined using the optional modalWidthMobile and modalHeightMobile attributes.

{% include picture.html
   image = "/assets/images/guide/contribute/formatting/example-optional-image-modal.png"
   retina = "/assets/images/guide/contribute/formatting/example-optional-image-modal@2x.png"
   mobile = "/assets/images/guide/contribute/formatting/example-optional-image-modal-mobile.png"
   mobileRetina = "/assets/images/guide/contribute/formatting/example-optional-image-modal-mobile@2x.png"
   modalImage = "/assets/images/guide/contribute/formatting/example-optional-image-modal@2x.png"
   modalImageMobile = "/assets/images/guide/contribute/formatting/example-optional-image-modal-mobile@2x.png"
   alt-text = "Optional image modal"
   width = 1600
   height = 800
   modalWidthMobile = 400
   modalHeightMobile = 400
%}

Image inline with the content

Images can also be inline with the content. This one is inline on desktop, but takes the full screen width on mobile.

<div class="center" markdown="1">

{% include image.html
   image = "/assets/images/guide/contribute/formatting/example-image-square.jpg"
   retina = "/assets/images/guide/contribute/formatting/example-image-square@2x.jpg"
   alt-text = "Example image"
   width = 400
   height = 400
   layout = "float-left-desktop"
%}

Mobile app stores do a good job of providing previews of what using an app will be like. Through copy, videos, images and reviews, users can make informed decisions about the product they are evaluating. Open-source software is typically downloaded via a website or Github, and each project decides what information to present.

Image inline on mobile and desktop

This next image is inline on both mobile and desktop.

<div class="center" markdown="1">

{% include image.html
   image = "/assets/images/guide/contribute/formatting/example-image-square.jpg"
   retina = "/assets/images/guide/contribute/formatting/example-image-square@2x.jpg"
   alt-text = "Example image"
   width = 100
   height = 100
   layout = "float-left"
%}

Mobile app stores do a good job of providing previews of what using an app will be like. Through copy, videos, images and reviews, users can make informed decisions about the product they are evaluating. Open-source software is typically downloaded via a website or Github, and each project decides what information to present.

</div>

Image slide gallery

A horizontal slide show of images. When the content is too wide for the screen, users can scroll.

<div class="image-slide-gallery">

{% include picture.html
   image = "/assets/images/guide/contribute/formatting/example-image-mobile-screen.png"
   retina = "/assets/images/guide/contribute/formatting/example-image-mobile-screen@2x.png"
   alt-text = "Example image"
   caption = "Example text"
   width = 250
   height = 541
%}

... more picture includes ...

</div>

Animations

Animations can be used to help communicate complicated information, or simply to add some fun effects to a page. Your animation should be a lottie format JSON file. You can create lottie animations using software like Adobe AfterEffects. Animations follow a similar code structure to images and can be formatted in many of the same ways.

When creating animations for the Guide, you must provide a fallback image for accessibility. If a user has javascript disabled or prefers reduced motion, then the image will be displayed instead of the animation.

Animation extends beyond content width

{% include lottie.html
   lottie-path = "/assets/animations/contribute/formatting/bitcoin-design-seal-miami-edition.json"
   image = "/assets/animations/contribute/formatting/bitcoin-design-seal-miami-edition.png"
   retina = "/assets/animations/contribute/formatting/bitcoin-design-seal-miami-edition@2x.png"
   alt-text = "Example animation"
   layout = "full-width"
%}

Animation fits content width

{% include lottie.html
   lottie-path = "/assets/animations/contribute/formatting/bitcoin-design-seal-miami-edition.json"
   image = "/assets/animations/contribute/formatting/bitcoin-design-seal-miami-edition.png"
   retina = "/assets/animations/contribute/formatting/bitcoin-design-seal-miami-edition@2x.png"
   alt-text = "Example animation"
   caption = "Bitcoin Design Community - Miami Edition"
   controls = true
%}

Animation controls

By default, animations loop continuously. You can override this by setting loop to “false”, and providing a play/pause toggle by setting controls to “true”.

{% include lottie.html
   lottie-path = "/assets/animations/contribute/formatting/bitcoin-design-seal-miami-edition.json"
   image = "/assets/animations/contribute/formatting/bitcoin-design-seal-miami-edition.png"
   retina = "/assets/animations/contribute/formatting/bitcoin-design-seal-miami-edition@2x.png"
   alt-text = "Example animation"
   loop = false
   controls = true
%}

Animation inline with content

Animations can also be inline with the content. This one is inline on desktop, but takes the full screen width on mobile.

<div class="center" markdown="1">

{% include lottie.html
   lottie-path = "/assets/animations/contribute/formatting/bitcoin-design-seal.json"
   image = "/assets/animations/contribute/formatting/bitcoin-design-seal.png"
   retina = "/assets/animations/contribute/formatting/bitcoin-design-seal@2x.png"
   alt-text = "Example animation"
   width = 400
   layout = "float-left-desktop"
%}

Bitcoin ipsum dolor sit amet. Peer-to-peer segwit mempool sats SHA-256, transaction satoshis halvening double-spend problem. Satoshi Nakamoto, peer-to-peer halvening hash, block height SHA-256 address Bitcoin Improvement Proposal full node? Full node, satoshis double-spend problem bitcoin soft fork! Satoshis UTXO double-spend problem halvening nonce private key halvening. Genesis block sats nonce, outputs, halvening hard fork block height halvening? Proof-of-work double-spend problem hash nonce SHA-256 sats, hash! Mining transaction, Merkle Tree, satoshis wallet.

</div>

Bitcoin ipsum dolor sit amet. Peer-to-peer segwit mempool sats SHA-256, transaction satoshis halvening double-spend problem. Satoshi Nakamoto, peer-to-peer halvening hash, block height SHA-256 address Bitcoin Improvement Proposal full node? Full node, satoshis double-spend problem bitcoin soft fork! Satoshis UTXO double-spend problem halvening nonce private key halvening. Genesis block sats nonce, outputs, halvening hard fork block height halvening? Proof-of-work double-spend problem hash nonce SHA-256 sats, hash! Mining transaction, Merkle Tree, satoshis wallet.

Animation inline on mobile and desktop

This next animation is inline on both mobile and desktop.

<div class="center" markdown="1">

{% include lottie.html
   lottie-path = "/assets/animations/contribute/formatting/bitcoin-design-seal.json"
   image = "/assets/animations/contribute/formatting/bitcoin-design-seal.png"
   retina = "/assets/animations/contribute/formatting/bitcoin-design-seal@2x.png"
   alt-text = "Example animation"
   width = 148
   layout = "float-left"
%}

Bitcoin ipsum dolor sit amet. Peer-to-peer segwit mempool sats SHA-256, transaction satoshis halvening double-spend problem. Satoshi Nakamoto, peer-to-peer halvening hash, block height SHA-256 address Bitcoin Improvement Proposal full node? Full node, satoshis double-spend problem bitcoin soft fork! Satoshis UTXO double-spend problem halvening nonce private key halvening. Genesis block sats nonce, outputs, halvening hard fork block height halvening? Proof-of-work double-spend problem hash nonce SHA-256 sats, hash! Mining transaction, Merkle Tree, satoshis wallet.

</div>

Bitcoin ipsum dolor sit amet. Public key, peer-to-peer miner satoshis Bitcoin Improvement Proposal hashrate, inputs, block height. Cryptocurrency transaction cryptocurrency hard fork nonce consensus inputs. Wallet blockchain satoshis, private key public key Satoshi Nakamoto hash. Cryptocurrency soft fork UTXO soft fork.

Lists

Breaking down content into lists is useful for readability. Here are examples of different list types.

Unordered list:

*   Item foo
*   Item bar
*   Item baz
*   Item zip

Item foo
Item bar
Item baz
Item zip

Ordered list:

 Item one
 Item two
 Item three
 Item four

Item one
Item two
Item three
Item four

Nested list

- level 1 item
  - level 2 item
  - level 2 item
    - level 3 item
    - level 3 item
- level 1 item
  - level 2 item
  - level 2 item
  - level 2 item
- level 1 item
  - level 2 item
  - level 2 item
- level 1 item

level 1 item
- level 2 item
- level 2 item
  - level 3 item
  - level 3 item
level 1 item
- level 2 item
- level 2 item
- level 2 item
level 1 item
- level 2 item
- level 2 item
level 1 item

Nesting an ol in ul in an ol

- level 1 item (ul)
  1. level 2 item (ol)
  1. level 2 item (ol)
    - level 3 item (ul)
    - level 3 item (ul)
- level 1 item (ul)
  1. level 2 item (ol)
  1. level 2 item (ol)
    - level 3 item (ul)
    - level 3 item (ul)
  1. level 4 item (ol)
  1. level 4 item (ol)
    - level 3 item (ul)
    - level 3 item (ul)
- level 1 item (ul)

level 1 item (ul)
1. level 2 item (ol)
2. level 2 item (ol)
  - level 3 item (ul)
  - level 3 item (ul)
level 1 item (ul)
1. level 2 item (ol)
2. level 2 item (ol)
  - level 3 item (ul)
  - level 3 item (ul)
3. level 4 item (ol)
4. level 4 item (ol)
  - level 3 item (ul)
  - level 3 item (ul)
level 1 item (ul)

Task list

- [ ] Hello, this is a TODO item
- [ ] Hello, this is another TODO item
- [x] Goodbye, this item is done

Hello, this is a TODO item
Hello, this is another TODO item
Goodbye, this item is done

Definition list

Typically used for lists of terms and descriptions.

{% include dl/open.html %}

{% include dl/item-open.html color="red" %}

“You will be shown your recovery phrase on the next screen”

{% include dl/item-middle.html color="red" %}

Prepares a user for what they are about to **see**.

{% include dl/item-close.html %}

{% include dl/close.html %}

“You will be shown your recovery phrase on the next screen”: Prepares a user for what they are about to see.
“Your recovery phrase is a group of 12 random words”: Explains to users what a recovery phrase is.
“Your recovery phrase is the only way to access your wallet if your phone is lost or stolen.”: Explains to users what the purpose of a recovery phrase is and why it’s important.
“If you lose your recovery phrase, you will no longer be able to access your wallet. Never share your recovery phrase with anyone. Anyone who has it can access your funds.”: Explains to users what the consequences of their behavior are, and how it can affect the safety of their funds.
“We recommend writing these words down in order on a piece of paper and storing it somewhere safe that you will remember.”: Guides and gives users actionable items on how to safely handle their recovery phrase.

Tables

| head1        | head two          | three |
|:-------------|:------------------|:------|
| ok           | good swedish fish | nice  |
| out of stock | good and plenty   | nice  |
| ok           | good `oreos`      | hmm   |
| ok           | good `zoute` drop | yumm  |

head1	head two	three
ok	good swedish fish	nice
out of stock	good and plenty	nice
ok	good `oreos`	hmm
ok	good `zoute` drop	yumm

Code embedding

// Javascript code with syntax highlighting.
var fun = function lang(l) {
  dateformat.i18n = require('./lang/' + l)
  return true;
}

# Ruby code with syntax highlighting
GitHubPages::Dependencies.gems.each do |gem, version|
  s.add_dependency(gem, "= #{version}")
end

Single-line code blocks

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

There’s a horizontal rule below this.

* * *

Embedding content from external sources

YouTube video embed

{% include youtube.html id="zKMRSLbQEqk" %}

Prototypes

Linking to prototypes is similar to embedding images. The main differences are the use of a different include and the addition of a link URL. The image is rendered as a link with a call-to-action button that lets users click through to the prototype.

Ensure that your images provide a good overview of the prototype content, so users can make an informed decision whether to give it a try.

{% include prototype.html
   link = "https://www.figma.com/proto/HggAJoHhLXPH0oZQEr1D4D/Bitcoin-Design-Guide?node-id=166%3A0&viewport=1714%2C3489%2C1&scaling=min-zoom"
   image = "/assets/images/guide/contribute/formatting/prototype-example.png"
   retina = "/assets/images/guide/contribute/formatting/prototype-example@2x.png"
   mobile = "/assets/images/guide/contribute/formatting/prototype-example-mobile.png"
   mobileRetina = "/assets/images/guide/contribute/formatting/prototype-example-mobile@2x.png"
   alt-text = "Example image"
   width = 800
   height = 500
%}

Prototype

Tips & recommendations

For additional useful information, but does not fit into the main flow of the content. This component has two presets, but can also be customized. Here are the presets:

Tips

{% include tip/tip.html %}

Sed in lacus vitae turpis lobortis ultrices. Aenean hendrerit nec elit in sagittis. Nulla mi ante, luctus vitae tincidunt ut, rhoncus ac ex. Morbi sit amet mauris est.

{% include tip/close.html %}

Tip

Sed in lacus vitae turpis lobortis ultrices. Aenean hendrerit nec elit in sagittis. Nulla mi ante, luctus vitae tincidunt ut, rhoncus ac ex. Morbi sit amet mauris est.

Recommendations

For highlighting moments when we think there is a particular approach or solution that the reader should strongly consider following.

{% include tip/recommendation.html %}

Most bitcoin products should use HD Wallets with Native Segwit addresses (unless focusing on maximum backwards compatibility).

{% include tip/close.html %}

Recommendation

Most bitcoin products should use HD Wallets with Native Segwit addresses (unless focusing on maximum backwards compatibility).

Custom use

You can also customize which color, title and icon the component should display with the following template. Available colors are red, orange, yellow, green, and blue.

{% include tip/open.html color="green" icon="check" label="My title" %}

Most bitcoin products should use HD Wallets with Native Segwit addresses (unless focusing on maximum backwards compatibility).

{% include tip/close.html %}

Do this

Most bitcoin products should use HD Wallets with Native Segwit addresses (unless focusing on maximum backwards compatibility).

Don't do this

Most bitcoin products should use HD Wallets with Native Segwit addresses (unless focusing on maximum backwards compatibility).

Facts

A table that provides specific descriptions based on standardized properties. Variations available are:

fact/pros.html
fact/cons.html
fact/dos.html
fact/donts.html
fact/variations.html
fact/products.html

{% include fact/pros.html %}

Can provide higher resistance to loss from theft and negligence.

{% include fact/close.html %}

Pros

Can provide higher resistance to loss from theft and negligence.

Cons

Require precise coordination of key-shares when signing, few advantages over multi-key setups with Schnorr signatures, individual implementations not interoperable.

Do's

When the target audience is knowledgeable, and risk of theft is higher than negligence.

Don'ts

When Schnorr signatures are available enabling multi-key setups.

Variations

Number of signatures required, location and distribution of pieces, signing procedure.

Products

Bitcoin wallet, BTC wallet, BeeTeeCee Wallet

Do’s and don’ts

This component allows for visual display and comparison of good and bad design implementations. The component consists of open, middle and close tags, between which regular markdown can be used.

{% include do/open.html label="Do" icon="check" color="green" %}

Provide clear error messages that tell users how to solve the problem.

{% include image.html
   image = "/assets/images/guide/contribute/formatting/example-image-square.jpg"
   retina = "/assets/images/guide/contribute/formatting/example-image-square@2x.jpg"
   alt-text = "Example image"
   width = 400
   height = 400
%}

{% include do/middle.html label="Don't" icon="forbid" color="red" %}

Write overly complex error messages that require deep technical knowledge.

{% include image.html
   image = "/assets/images/guide/contribute/formatting/example-image-square.jpg"
   retina = "/assets/images/guide/contribute/formatting/example-image-square@2x.jpg"
   alt-text = "Example image"
   width = 400
   height = 400
%}

{% include do/close.html %}

Do

Provide clear error messages that tell users how to solve the problem.

Don't

Write overly complex error messages that require deep technical knowledge.

Footnotes

With footnotes, you can add notes and references without them appearing on page.

Here's a simple footnote[^1]

Here’s a simple footnote¹

[^1]: https://bitcoin.design "Footnote with a caption"

Next, let’s move on to the Glossary which explains common bitcoin terms you may come across.

Glossary

https://bitcoin.design “Footnote with a caption” ↩

Formatting

Basic markdown formatting #

Text formatting #

Headers #

h1 header

h2 header #

h3 header #

H4 header #

h5 header #

h6 header #

Blockquote #

Links #

External Links #

Internal links #

Button links #

Images #

Image fits content width #

Image viewable in larger modal #

Image viewable in larger modal with alternate mobile image #

Image inline with the content #

Image inline on mobile and desktop #

Image slide gallery #

Animations #

Animation extends beyond content width #

Animation fits content width #

Animation controls #

Animation inline with content #

Animation inline on mobile and desktop #

Lists #

Unordered list: #

Ordered list: #

Nested list #

Nesting an ol in ul in an ol #

Task list #

Definition list #

Tables #

Code embedding #

Single-line code blocks #

There’s a horizontal rule below this. #

Embedding content from external sources #

YouTube video embed #

Prototypes #

Tips & recommendations #

Tips #

Tip

Recommendations #

Recommendation

Custom use #

Do this

Don't do this

Facts #

Pros

Cons

Do's

Don'ts

Variations

Products

Do’s and don’ts #

Do

Don't

Footnotes #

Basic markdown formatting

Text formatting

Headers

h2 header

h3 header

H4 header

h5 header

h6 header

Blockquote

Links

External Links

Internal links

Button links

Images

Image fits content width

Image viewable in larger modal

Image viewable in larger modal with alternate mobile image

Image inline with the content

Image inline on mobile and desktop

Image slide gallery

Animations

Animation extends beyond content width

Animation fits content width

Animation controls

Animation inline with content

Animation inline on mobile and desktop

Lists

Unordered list:

Ordered list:

Nested list

Nesting an ol in ul in an ol

Task list

Definition list

Tables

Code embedding

Single-line code blocks

There’s a horizontal rule below this.

Embedding content from external sources

YouTube video embed

Prototypes

Tips & recommendations

Tips

Recommendations

Custom use

Facts

Do’s and don’ts

Footnotes