quickstart-for-markdown-users.md

Quick Start for Markdown users

Djot is a lot like Markdown. Here are some of the main differences you need to be aware of in making the transition.

Blank lines

In djot you need blank lines around block-level elements. Hence, instead of

This is some text.
## My next heading

you must write

This is some text.

## My next heading

Instead of

This is some text.
``` lua
local foo = bar.baz or false
```

you must write

This is some text.

``` lua
local foo = bar.baz or false
```

Instead of

Text.
> a blockquote.

you must write

Text.

> a blockquote.

And instead of

Before a thematic break.
****
After a thematic break.

you must write

Before a thematic break.

****

After a thematic break.

Lists

A special case of this is that you always need a blank line before a list, even if it's a sublist. So, while in Markdown you can write

- one
  - two
  - three

in djot you must write

- one

  - two
  - three

Headings

There are no Setext-style (underlined) headings, only ATX- (#) style.

Heading content can extend over several lines, which may or may not be preceded by # characters:

## This is a single
## level-2 heading

### This is a single
level-3 heading

As a result, headings must always have a blank line following.

Trailing # characters in a heading are read as part of the content and not ignored.

Code blocks

There are no indented code blocks, only fenced with ```.

Block quotes

You need a space after the > character, unless it is followed by a newline.

Emphasis

Use single _ delimiters for regular emphasis and single * delimiters for strong emphasis.

Links

There is no special syntax for adding a title to a link, as in Markdown:

[link](http://example.com "Go to my website")

If you want a title attribute on a link, use the general attribute syntax:

[link](http://example.com){title="Go to my website"}

Hard line breaks

In Markdown you can create a hard line break by ending a line with two spaces. In djot you use a backslash before the newline.

A new\
line.

Raw HTML

In Markdown you can just insert raw HTML "as is." In djot, you must mark it as raw HTML:

This is raw HTML: `<a id="foo">`{=html}.

Here is a raw HTML block:

``` =html
<table>
<tr><td>foo</td></tr>
</table>
```

Tables

Pipe tables always require a pipe character at the start and end of each line, unlike in many Markdown implementations. So, this is not a table:

a|b
-|-
1|2

but this is:

| a | b |
| - | - |
| 1 | 2 |

That's enough to get started!

Here we have just focused on things that might trip up Markdown users. If you keep these in mind, you should be able to start using djot without looking at any more documentation.

However, we haven't discussed any of the things you can do in djot but not Markdown. See the syntax description to find about the new constructions that are available.