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.
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.
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.
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.
{%includepicture.htmlimage="/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=250height=541modalWidth=250modalHeight=541%}
This image has some small details, so click on it to see it in a modal window.
Image viewable in larger modal with alternate mobile image #
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.
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.
This next image is inline on both mobile and desktop.
<div class="center" markdown="1">
{%includeimage.htmlimage="/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=100height=100layout="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>
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.
A horizontal slide show of images. When the content is too wide for the screen, users can scroll.
<div class="image-slide-gallery">
{%includepicture.htmlimage="/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=250height=541%}
... more picture includes ...
</div>
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.
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.
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”.
Typically used for lists of terms and descriptions.
{%includedl/open.html%}{%includedl/item-open.htmlcolor="red"%}
“You will be shown your recovery phrase on the next screen”
{%includedl/item-middle.htmlcolor="red"%}
Prepares a user for what they are about to **see**.
{%includedl/item-close.html%}{%includedl/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.
| 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 |
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.
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.
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:
{%includetip/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.
{%includetip/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.
For highlighting moments when we think there is a particular approach or solution that the reader should strongly consider following.
{%includetip/recommendation.html%}
Most bitcoin products should use HD Wallets with Native Segwit addresses (unless focusing on maximum backwards compatibility).
{%includetip/close.html%}
Recommendation
Most bitcoin products should use HD Wallets with Native Segwit addresses (unless focusing on maximum backwards compatibility).
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.
{%includetip/open.htmlcolor="green"icon="check"label="My title"%}
Most bitcoin products should use HD Wallets with Native Segwit addresses (unless focusing on maximum backwards compatibility).
{%includetip/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).
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
{%includefact/pros.html%}
Can provide higher resistance to loss from theft and negligence.
{%includefact/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.
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.
{%includedo/open.htmllabel="Do"icon="check"color="green"%}
Provide clear error messages that tell users how to solve the problem.
{%includeimage.htmlimage="/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=400height=400%}{%includedo/middle.htmllabel="Don't"icon="forbid"color="red"%}
Write overly complex error messages that require deep technical knowledge.
{%includeimage.htmlimage="/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=400height=400%}{%includedo/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.