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

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

> This is a blockquote text.

This is a blockquote text.

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

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/style/example-image-wide-desktop.jpg"
   retina = "/assets/images/style/example-image-wide-desktop@2x.jpg"
   mobile = "/assets/images/style/example-image-wide-mobile.jpg"
   mobileRetina = "/assets/images/style/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/style/example-image-wide-desktop.jpg"
   retina = "/assets/images/style/example-image-wide-desktop@2x.jpg"
   mobile = "/assets/images/style/example-image-wide-mobile.jpg"
   mobileRetina = "/assets/images/style/example-image-wide-mobile@2x.jpg"
   alt-text = "Example image"
   width = 1600
   height = 800
%}

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/style/example-image-square.jpg"
   retina = "/assets/images/style/example-image-square@2x.jpg"
   alt-text = "Example image"
   width = 400
   height = 400
   layout = "float-left-desktop"
%}

Mobile app stores do a good job at 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 from 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/style/example-image-square.jpg"
   retina = "/assets/images/style/example-image-square@2x.jpg"
   alt-text = "Example image"
   width = 100
   height = 100
   layout = "float-left"
%}

Mobile app stores do a good job at 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 from Github and each project decides what information to present.

</div>

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 with HTML syntax.

<dl>
<dt>Name</dt>
<dd>Godzilla</dd>
<dt>Born</dt>
<dd>1952</dd>
<dt>Birthplace</dt>
<dd>Japan</dd>
<dt>Color</dt>
<dd>Green</dd>
</dl>

Name: Godzilla
Born: 1952
Birthplace: Japan
Color: Green

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

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"

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 #

Images #

Image fits content width #

Image inline with the content #

Image inline on mobile and desktop #

Lists #

Unordered list: #

Ordered list: #

Nested list #

Nesting an ol in ul in an ol #

Task list #

Definition with HTML syntax. #

Tables #

Code embedding #

Single-line code blocks #

There’s a horizontal rule below this. #

Embedding content from external sources #

YouTube video embed #

Prototypes #

Footnotes #