The Markdown Editor

The Markdown Editor is the simplest of the three editors available in Publii; what it lacks in features in makes up for in sheer speed. Using shorthand symbols such as hashes, you can insert various HTML elements without the need to worry about opening and closing tags. This process allows for rapid creation of content; great if you are writing content that doesn't require many expansive options such as documentation or instructions. 

When writing in HTML, each piece of content must be wrapped in HTML Tags; for example, a normal paragraph will be wrapped in a paragraph tag:

<p>This is a paragraph</p>

With Markdown, paragraph tags are automatically inserted into the content, and more complex tags such as Headers and Links are added using shortcuts. Which HTML tags have shortcuts depends on the markdown editor that is used; in the case of Publii, the Markdown engine is SimpleMDE which, as the name suggests, offers a simple, fast engine for writing. In the following sections we'll cover the various markdown shortcuts available in Publii.

Adding a Post Title

When first opening the Markdown Editor to create a post, you will be presented with a blank space with two fields available, one marked Add Post Title, and the other marked Write Here.... 

[image=blank markdown editor post]

The Post Title is required before the post can be saved, so click on the field and insert your title as soon as possible. You can of course change it at any time, but adding a title early will save you any trouble saving later. 

The section marked Write Here is for the main content of your post, and we'll cover how Markdown shortcuts can be used to make writing this content easy.

Markdown Shortcuts

To use these shortcuts, add the specified symbol at the beginning of the line; this will ensure that it is converted correctly to HTML. Alternative, you may also use the specified keyboard shortcut to insert the required symbol:

Inserting Headings with Markdown

The heading elements in HTML (H1-H6) are used to create titles for your content. Each heading 'level' is used to show where a particular title is in the post hierarchy; for example, the main title of a page or article will use the H1 heading, while each subsection of the article will use an H2 heading. If each section has its own subsections, then they will usually use the next heading down; a subsection under a H2 heading will use a H3 heading, and so one. This creates a structure to your content that is easily understandable to both people and computers! In Publii, the main H1 title is created by the 'Title' field in the post editor, and the other headings may be added manually as you create your content. With markdown shortcuts, this can be done very quickly and easily. You can of course add multiple H1 elements should you wish, but this is not usually recommended for SEO purposes.

To insert a heading using markdown, you add hashes (#) corresponding to the heading you want to insert before your title. So, to insert a Heading 2 element (H2), you would write:

## My heading 2 title

...then hit enter. This content will be automatically converted to a Heading 2 element in HTML. If you want to insert a Heading 3 (H3) element, just add three hashes before the title, and so on.

Inserting Lists with Markdown

There are two types of lists that are common in HTML, and in writing in general; ordered lists, or lists with numbered items, and unordered lists, which use bulletpoints instead of numbers for each item. Inserting them using markdown is extremely fast and easy. For an unordered list, type a star (*) or a hyphen/dash (-) followed by a space before the first item's text in a list. When you hit enter, the text will automatically change to a bulletpoint item. For example, typing:

* The first item in my unordered list.

...and hitting the enter key will add a bulletpoint before the text, and automatically create a second bulletpoint for your new line of text, so you can add the next item. Simply add your next item, then hit enter again to create a third item etc...Once you've added all the items you want, pressing enter on a blank item will end the list.

Inserting ordered lists works in exactly the same way, but instead of using a star or hyphen, you can just start to write the list using "1. ". The item will automatically be formatted into a list. Once you've added enough items, just hit enter on a blank item to end the list.

Adding Bold, Italic or Strikethrough Text with Markdown

Markdown can automatically change your text to be bold or italic by wrapping the text in the appropriate symbol, in this case a star (*) for italics, two stars (**) for bold, and two tildes (~~) for strikethrough. To make a sentence bold, you should add two stars before and after the text. For italic, add one star before and after the text, and for strikethrough, two tildes before and after the text:

**This text will be bold**. 
*This text will be italic*.
~~This text will be strikethrough~~
This text will be unchanged.

The Markdown Editor will change the text as soon as you add the symbols before a word, so you'll know immediately that is has worked. The Tilde key is usually located at the top-left corner of a standard QWERTY keyboard; if you are having trouble finding it, you may either use the keyboard shortcut for strikethrough text (Ctrl+U) or you can use the Alt Code; hold down the Alt key, then press the numbers 126, then release the Alt key to insert a tilde.

Inserting Links with Markdown

Links are easy to insert into your content with Markdown. First, you can set the text of the link using square brackets [ ] around the word you want to create a link with, and then regular brackets ( ) around the link that you want to link to:

[link text](link URL)

You may also create a link by pressing the CTRL+K or Command+K keys on your keyboard to open the Insert/Edit Link pop-up. 

[image]Insert link popup in the markdown editor[/image]

In this pop-up, the first option you will see is:

• Select Link Type - Sets the type of content you want to link to; select from a Post Link, Tag Link, Author Link, Frontpage Link, Custom Link, or a File From File Manager.

This option defines what type of content you want to link to. Post, Tag, and Author Links allows you to link to a specific post, tag or author page on your Publii site. Frontpage Links point only to the homepage of the site. Custom Links points to a URL that isn't part of your Publii site, and File From File Manager lets you link to a file in your site files that users can view or download. 

After selecting the type of link you want to insert, the next field will change depending on the link type. For Post, Tag or Author Links, the second field will contain a drop-down list where you can choose the Post, Tag, or Author Page that you want to link to. If you have many items in the list you can start to type in the field to dynamically filter the list.

For Custom Links, the second field will be used to insert the URL that you want to link to. Make sure to enter the full address to avoid creating a broken link.

For File From File Manager, the second field will function much like the Post, Tag, or Author Page field; a drop-down list that contains all the files currently stored in Publii's file manager. Again, you can dynamically filter the list by typing the name of the file you want to find in the field.

With the link address set, the final field, Link Label, lets you define the text of the link as it will appear in your content. Once you have filled out all fields, click the OK button to create the link.

Inserting Code

When we talk about inserting code into our content, we don't mean code that will be run by the browser. Instead, it refers to a way of styling the text so that it is distinct and clear from the rest of the page content; you can see it used throughout this page when demonstrating what to enter into the markdown editor to change the text styling, in fact, we'll use it right now to show you how to insert code into your content:

`This text will be displayed as code content`

However, there are in fact two different types of code content that can be entered, which we refer to as Inline Code and, simply, Code. The difference is minimal in practice, but important for users that wish to insert larger code blocks. 

Inline Code, which is inserted as in the above example, is used to display a single line of code; the length doesn't matter, but the content will be wrapped to a new line. To insert Inline Code, we need to add a Grave Accent before and after our code text:

`This is an example of inline code in markdown; note that this long sentence wraps to a new line without any additional line breaks or other separators`

For reference, the Grave Accent is not an apostrophe, though it looks similar. It will usually be on the top-left key of a standard QWERTY keyboard, though depending on the language your OS uses you may need to hold the Shift key to access it. 

Contrary to inline code, the Code insert will maintain formatting such as line breaks. This is particularly useful when displaying code that has multiple separate lines that will not work correctly if inserted into a single line. To create a Code block, simply add three Grave Accents before or on the line above the text, and another three on a separate line after the end of the text you wish to convert to a code block:

```

This is an example of Code in markdown.

Line breaks, including blank lines, are maintained in this block.

This makes it easier users to read more extensive code listings.

```

If you should be having trouble finding the Grave Accent key on your keyboard, you may also enter it (on most European and American OS') by holding down the Alt or Command key and pressing the numbers 96, then releasing the Alt key. 

Inserting Blockquotes 

A Blockquote is a piece of text that is styled to appear larger with a quotation mark; useful for drawing attention to an important quote from your content or to include a quote from another source that is relevant to your content:

[image=blockquote example]

To insert a blockquote, insert a Greater-than symbol before the line you wish to convert to a blockquote, followed by a space:

> This will be the blockquote text

Pressing enter will continue the blockquote; content added onto a new line will be wrapped with the existing lines to form one continuous string of text:

> These two lines will appear
> as a single line of text in the blockquote

To finish the blockquote, hit enter twice just as you would when ending an ordered or unordered list.

Inserting Images

Adding images to your content functions similiarly to adding links in Markdown. First, you set the image description of the image in square brackets preceded by an exclamation mark ![ ]. Then, you set the image using the URL of the image in regular brackets ( ). For example, to insert a image called image1, and give it the description 'picture' in the text, we would write:

![picture](mytest.com/image1.png)

Alternatively, you can drag and drop images from your computer directly into the Markdown Editor in Publii, and it will automatically add the picture to the website files and create the link to display the image. At this point, you can change the 'image description' text to your own description text.