Markdown Documentation

Creating beautiful documents from markdown is really easy with Remarq. Here's a quick introduction to the most useful things you should know.

Title pages and meta data with YAML

You can automatically add title pages to your document by adding a few simple lines to the top of your document document.

A block of YAML configuration data at the beginning of your document should be delimited by a line of three hyphens (---) at the top and a line of three hyphens (---) at the end of the data block.

If you include 'title', 'author', and 'date' fields they will be used on the title page of the generated document.

---
title: A simple document
author: Jeremy Green
date: Jan 2015
tags: [nothing, nothingness]
notes: |
  Send to editor
language: en-US
---

Table of Contents

A table of contents can be automatically generated for your document by checking the box for "Table of Contents" in your style setup. You can control how many levels of headings are included in the TOC by changing the "TOC Depth" setting. (This will probably move to being a document level setting very soon.)

Use H1 for your main section headings

It's common to say that a document should have only a single H1 level heading, and that's usually the title of the document. Since we have a title page accomplishing that job (and since it's a PDF and not a real H1 tag) it makes sense to use H1 for each of the major sections of the document. This will produce the best results for the automatically generated table of contents.

An H1 level header is indicated by a new line that starts with a single #.

# This is an H1 level heading

Section Title Pages

There are two ways to create title pages for each major document section.

  1. In your style, check the box in the "Top Level Headings (H1)" section that says "Create section title pages". Doing this will set each H1 level heading on its own page. You can alter the background and font color of that page by setting the background and font color for the H1 headings.

  2. For more complex section title pages you can wrap content in \sectionTitle and \stopSectionTitle tags as shown below. The font color and page background color are controlled in the "Section Title Pages" section of your style.

\sectionTitle

# Here's a heading on a title page

And here is a paragraph of text on the title page. You can include
anything you want on the title page.

## Even second level heading

* Or a list
* Of items

\stopSectionTitle

Sub Section & Sub-sub Section Headings

Sub sections should be started with an H2 level heading, denoted with 2 # characters.

You can further structure your document with sub-sub section headings of the H3 level (3 # characters).

## This is a sub section level heading

### And this is a sub-sub section heading

Inline Formatting

To emphahize some text (with italics) you should surround it with * or _ characters.

This text is _emphasized with underscores_, and this
is *emphasized with asterisks*.

Doubling those characters will produce strong emphasis (bolded text).

This is **strong emphasis** and __with underscores__.

Surrounding text with two ~ characters will strike out that text.

This text ~~contains a strike out~~.

Block Quotes

Block quotes are indicated by starting each line of the block with the > character.

> Literally better than anything else in the world.
> - Kai Davis on Hobo Standard

Lists

One thing to note: lists (bulleted or ordered) that have a line of text before them need to have a line-break before the list starts. Let's take a look at how this should be formatted:

This is a line of text. **This is bold text** and _this is italic text_!

* This is a list item
* And another list item
    - This is a sub list item
    - And another sub list item
* Yet another main list item

This is some more text.

When using a list in your document, make sure that you include a linebreak separating the list from the content. Below, you'll find additional examples for using bulleted and ordered lists.

Bulleted Lists

Bulleted list items should begin each line with *, + or -. Indent list items by 4 spaces to create sub lists.

* This is a list item
* And another list item
    - This is a sub list item
    - And another sub list item
* Yet another main list item

Ordered Lists

Ordered list items should begin each line with #.. This will allow the numbers to be placed automatically based on the items position within the list, and you don't have to worry about keeping the numbers in order.

#. This is item 1
#. This is item 2
    #. This is item 2.1

Horizontal Rules

You can create horizontal rules by placing three or more *, -, or _ characters on a single line. They may optionally be separated with spaces.

---------------

*  *  *  *

Line breaks

In order to create a single line break, as opposed to a paragraph break, you can leave two blank spaces at the end of a line, then start a new line. The second line will appear directly below the first line.

This is the first line, it has two blank spaces at the end.  
This is the next line, which appears directly underneath the first.

You can also use <br/> to force line breaks.

If you need to create blank space within a document you can use &nbsp; along with <br/>.


Here's a line of text followed by some blank space.

<br/>&nbsp;
<br/>&nbsp;
<br/>&nbsp;

And here's another line, after the blank space.

Manual Page Breaks

If you need to force a page break you can accomplish that with the \newpage command.

This will be on one page.

\newpage

And this will be on the next one.

Links

Enclosing a URL or email address in pointy brackets will print the text and make it a clickable link.

<http://www.octolabs.com>
<jeremy@octolabs.com>

Inline links can be created by surrounding the text in square brackets and including the link directly afterwards in parentheses.

Please visit [my website.](http://www.octolabs.com/)

Images

A link preceded by an exclamation point will be an image. If the image occurs by itself in a paragraph the image will be rendered as a figure, with the "link text" acting as the figure label.

![The OctoLabs Logo.](http://www.octolabs.com/images/octologo.png)

Image Placement

By default images will "float" to allow for the optimum use of space on the page. This means that an image may appear in the final document somewhat later than where it appears in the source. You can force an image to appear exactly where you put it by including a (LaTeX style) non-breaking space after the image. A non breaking space consists of a back slash (\) followed by a space ().

![The OctoLabs Logo.](http://www.octolabs.com/images/octologo.png)\ 

Please note that an image forced into position in this way will not have a figure label.

Image Width

You can force an image to display at a certain size by including a width after the image location.

![The OctoLabs Logo.](http://www.octolabs.com/images/octologo.png){width=1in}

As a general rule if you want things to appear at their "natural size" you should take the pixel dimensions of the image and divide by 96. So, for a logo that is 300px across you'd probably want to use a width of 3.125 inches. If you use a width larger than 3.125 the image would appear to be scaled up, and if you use something smaller than 3.125 the image would appear to be scaled down. You should be able to use any size you want that gets things to look the way you want it.

You can also use a percentage.

![The OctoLabs Logo.](http://www.octolabs.com/images/octologo.png){width=50%}

Using Dropbox

To host your images in Dropbox, you need to make sure that they are in your ~/Dropbox/Public folder. Then you can copy the public link to the image.

Copying a public Dropbox link

If you try to 'Copy Public Link' for an item that is not in your ~/Dropbox/Public folder you will get a URL that will not work.

Footnotes

Footnotes can be included with the following syntax.

This is a claim that requires supporting information.[^info]

[^info]: Supporting info...

The footnote itself can appear anywhere within the document, but it's most convenient to keep it close to the referenced text in your markdown document. The identifiers in footnote references may not contain spaces, tabs, or newlines.

Code Blocks

Code blocks begin with a row of three or more tildes (~) or backticks (`) and end with a row of tildes or backticks that must be at least as long as the starting row.

```
if(val == 42){
  alert('the answer!');
}
```

You can also attach attributes to a code block to get syntax highlighting and line numbering.

~~~ {#mycode .ruby .numberLines startFrom="100"}
require 'open-uri'
data = open('http://www.octolabs.com/').read
~~~

Custom Title Pages

Please note: This premium feature is not available on all plans.

To get a custom title page for the whole document you can use a YAML block to set a title_image attribute.

---
title: A simple document
author: Jeremy Green
title_image: http://example.com/image.jpg
---

For best results the aspect ratio of the image should be 8.5x11.

Importing PDFs

Please note: This premium feature is not available on all plans.

You can import other PDFs into your document with the \importPdf command.

\importPdf{http://example.com/something.pdf}{white}

The first set of curly braces is required and contains the URL of the pdf.

The second set of curly braces is required, but you can leave it blank. It sets the background color of the page in case the pdf doesn't fill the page.

For best results the pdf pages should be 8.5x11 inches.

Full page image imports

Please note: This premium feature is not available on all plans.

You can import an image as a full page by using the \fullPageImage command.

\fullPageImage{http://example.com/image.jpg}{black}

The first set of curly braces is required and contains the URL of the image. Formats can be png or jpg.

The second set of curly braces is required, but you can leave it blank. It sets the background color of the page in case the image doesn't fill the page.

For best results the aspect ratio of the image should be 8.5x11.

Additional Info

Remarq uses Pandoc flavored markdown, so you can check that documentation for more in depth info.

Sit tight, your document is being built...

Downdload Your PDF

Oh no! We hit a snag processing your document.

Markdown Help