# Formatting

Markdown .md pages are plain text documents with a simple human readable syntax that aims to make writing for the internet easier.

No special software is required to create an .md file. Any basic text editor will do.

Please see markdownguide.org for a full demonstration of the formatting possibilities and best practices.

View the actual formatting.md file used to create this page.

# Quick start

The following sample demonstrates a very basic .md page sample with page title and one paragraph.

# Page title here

This is just a paragraph.

We can build on the above by more formatting options such as bold text, images, and lists.

# Page title here

This is just a paragraph.

The page can contain both [internal](/README.md) and [external](https://example.com) links.

![Your logo](logo.png)

Another paragraph with **bold**, _italic_, ~~strikethrough~~, and `code` samples.

#### Lists

- First item
- Second item
- Third item

1. First item
2. Second item
3. Third item

> "Cool! This is a quotation."

Need to draw attention to something? Use an alert.

At a very basic level, to create a new page for your Retype project, do the following:

  1. Create an .md file
  2. Add a # title
  3. Start writing

In addition to the standard Markdown options (see cheat sheet), Retype includes some nice extras...

# Emojis 😻

Retype uses Mojee.io to find emoji :shortcodes: within your document and replace with actual emoji characters. πŸ‘

You can place emoji :shortcodes: anywhere within your document, such as :smile: πŸ˜„ or :unicorn_face: πŸ¦„.

Use Mojee to search for your favorite emojis and paste the :shortcode: into your .md document.

πŸ˜€ πŸ˜ƒ πŸ˜„ 😁 πŸ˜† πŸ˜… πŸ˜‚ πŸ˜‰ 😊 πŸ˜‡
😍 😘 ☺️ 😚 πŸ˜‹ πŸ˜› 😜 😝 😐 πŸ˜‘
😢 😏 πŸ˜’ 😬 😌 πŸ˜” πŸ˜ͺ 😴 😷 😎
πŸ˜• 😳 πŸ˜₯ 😒 😭 😱 πŸ˜– 😣 😞 πŸ˜“
😩 😫 😀 😑 😠 😈 πŸ’€ 😻 πŸ™ˆ πŸ™Š
πŸ’‹ πŸ’˜ πŸ’– πŸ’— πŸ’“ πŸ’ž πŸ’• πŸ’” ❀️ πŸ’›
πŸ’š πŸ’™ πŸ’œ πŸ’― πŸ’₯ πŸ‘‹ βœ‹ πŸ‘Œ ✌️ πŸ‘ˆ
πŸ‘‰ πŸ‘‡ πŸ‘ πŸ‘Š πŸ‘ πŸ™Œ πŸ™ πŸ’ͺ πŸ‘€ πŸ’
🌸 🌹 🌚 β˜€οΈ ⭐ ⚑ πŸ”₯ ✨ πŸŽ‰ β™₯️
πŸ‘‘ 🎢 πŸ“· ➑️ ⬅️ ▢️ ♻️ βœ… βœ”οΈ πŸ”΄

# Alerts

Alert components help to highlight important messages for the reader.

To create an alert, just surround a block of text or any markdown content with !!!.

This is an alert.

This is an alert.

# Alert title

Alerts can also have titles. Add a space, then add your title, such as !!! My title.

!!! My title
This is an alert.

This is an alert.

# Alert variants

Alerts come in 6 different flavors which can be specified by passing a variant immediately after the !!!, such as !!!danger.

Variant Color
primary (default) blue
secondary gray
success green
danger red
warning yellow
info light-blue
light light
dark dark
contrast light or dark depending on time of day

# Alert demo

!!!primary Primary
This is a `primary` alert.

!!!secondary Secondary
This is a `secondary` alert.

!!!success Success
This is a `success` alert.

!!!danger Danger
This is a `danger` alert.

!!!warning Warning
This is a `warning` alert.

!!!info Info
This is a `info` alert.

!!!light Light
This is a `light` alert.

!!!dark Dark
This is a `dark` alert.

!!!contrast Contrast
This is a `contrast` alert.

This is a primary alert.

This is a secondary alert.

This is a success alert.

This is a danger alert.

This is a warning alert.

This is a info alert.

This is a light alert.

This is a dark alert.

This is a contrast alert.

# Tabs

Tabs are super simple to configure by just surrounding a block of text with ||| and including a title.

||| Tab 1
This is a Tab

This is a Tab

# Multiple tabs

Multiple Tabs can be configured by stacking ||| blocks.

||| Tab 1
This is a Tab
||| Tab 2
This is another Tab
||| Tab 3
Wow! Yet another tab :+1:

This is a Tab

This is another Tab

Wow! Yet another tab πŸ‘

# Panels

A Panel is created by surrounding a block of content with +++ and including a title.

+++ My Panel
This is a Panel. Expanded by default.

This is a Panel. Expanded by default.

# Collapsed panel

By default, Panels are collapsible and will be in there expanded state. You can configure Panels to initially render in their collapsed state by using ++-.

++- My Panel
This is a collapsed Panel. :+1:

This is a collapsed Panel. πŸ‘

# Lists

# Checklist

- [x] Item 1
- [x] Item 2
- [ ] Item 3
  • Item 1
  • Item 2
  • Item 3

# Bullet list

- Item 4
- Item 5
- Item 6
  • Item 4
  • Item 5
  • Item 6

# Numbered list

1. Item 7
2. Item 8
3. Item 9
  1. Item 7
  2. Item 8
  3. Item 9

# Buttons

A Button uses the same syntax as a hyperlink, but is prefixed with a !button type.

[Click me](https://example.com/)         <-- a link

[!button Click me](https://example.com/) <-- a button

# Basic

No link Internal link External link

# Variants

[!button variant="primary" text="Primary"]
Variant Example
primary (default) Primary
secondary Secondary
success Success
danger Danger
warning Warning
info Info
light Light
dark Dark
contrast Contrast

# Corners

[!button text="Default"]
[!button corners="square" text="Square"]
[!button corners="pill" text="Button Pill"]
Size Example
Default Default
square Square
pill Button Pill

# Size

[!button size="m" text="Medium"]
Size Example
xs XSmall
s Small
m (default) Medium
l Large
xl XLarge
2xl 2XLarge
3xl 3XLarge

# Icon and Emoji

# Octicons

[!button variant="info" icon="person" text="User"]
[!button variant="primary" icon="paper-airplane" iconAlign="right" text="Send"]

User Send

# Emoji

[!button variant="light" icon=":heart:" text="Like"]
[!button variant="info" icon=":rocket:" iconAlign="right" text="Rocket"]

Like Rocket

# Image

[!button icon="/static/retype-logo.svg"]

Visit website

# Inline

This is a paragraph with a Button.

# Block

[!button Button 1]

[!button Button 2]

Button 1

Button 2

# Code blocks

# Title

Retype includes the functionality to set a title on your markdown code blocks.

``` Code block title
var msg = "Set a code block title";
Code block title
var msg = "Set a code block title";

The title can be used in conjunction with the code reference type.

```js Code block title
var msg = "Set a code block title";
Code block title
var msg = "Set a code block title";

# Line numbers

Adding or removing line numbering to your code blocks can be configured by adding the # specifier character to the first line after the reference language.

```js #
var msg = "hello, world";
var msg = "hello, world";

You can also add a title after the #:

```js # Your title here
var msg = "hello, world";
Your title here
var msg = "hello, world";

# Disable line numbers

Explicitly disabling the line numbering within code blocks is possible by using the !# specifier instead of #:

```js !#
var msg = "";
var msg = "";

# File download

A static file download component can be configured by using the !file specifier in a link.

File download component
[!file Sample](../static/sample.txt)

sample.txt 36B

Clicking anywhere within the file download component will trigger the web browser to download the static file.

# Reference link

A special type of reference link can be configured by using the !ref specifier in a link.

Reference link component
[!ref Getting Started](../guides/getting_started.md)

Getting Started

Clicking anywhere within the reference link component will navigate to that new page.

From a functionality perspective, there is no difference betwen a !ref component and a regular hyperlink. The difference between the two is just how they are presented.

# Image alignment

Retype includes extra functionality for the custom alignment of images on the page.

For instance, you can specify for an image to align to the left or right and have the text flow around the image.

Another plus option for Blog pages or pages with layout: central help to position the image slightly overlapping the left or right content margins.

Position Markdown Description
center ![Caption](photo.jpg) Center aligned in its container (default)
left -![Caption](photo.jpg) Float left aligned
leftplus --![Caption](photo.jpg) Float left aligned with some negative left offset
right ![Caption](photo.jpg)- Float right aligned
rightplus ![Caption](photo.jpg)-- Float right aligned with some negative right offset
centerplus -![Caption](photo.jpg)- Center aligned plus negative offset both sides

Here's a sample page demonstrating all the image alignment scenarios, see...

Image alignment options

The plus alignment options only apply when the page is layout: central or layout: blog.

For default page layouts with a left navigation and/or the right table of contents, the plus positions will fallback to their non-plus equivalents. For instance, rightplus will fallback to right and the centerplus will fallback to center.