The Markdown Editor

The Markdown Editor is the simplest of the three editors available in Publii; what it lacks in visual editing tools it makes up for in 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; useful if you are writing content such as documentation or instructions.

When writing in HTML, text is usually 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 when the content is converted to HTML, and more complex elements such as Headings and Links are added using shortcuts. Which HTML elements have shortcuts depends on the Markdown editor that is used. In the following sections we'll cover the various Markdown shortcuts available in Publii.

The same Markdown syntax can also be used when editing a page 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 Start writing....

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 Start writing... 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

For headings, lists and blockquotes, add the specified symbol at the beginning of the line, followed by a space. For inline formatting, such as bold or italic text, place the symbols around the text you want to format. Alternatively, you may use the keyboard shortcuts listed below to insert the required symbols.

In the table, Ctrl/Cmd means Ctrl on Windows and Linux, or Command on macOS. The Ctrl+H heading shortcut is available on Windows and Linux; on macOS, type the heading markers directly. Repeated uses of Ctrl+H cycle through heading levels, so Ctrl+H (twice) means pressing the shortcut twice, starting from a normal paragraph.

The Markdown symbols remain visible while you edit. The editor styles parts of the text to help you recognise the formatting, and Publii converts the Markdown to HTML when generating a preview or building your website.

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 usually 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 an H2 heading will use an H3 heading, and so on. This creates a structure to your content that is easily understandable to both people and computers. In Publii, themes usually display the post's title as the main H1 heading, and the other headings may be added manually as you create your content. With Markdown shortcuts, this can be done quickly and easily. Start the main sections of your post with H2 headings when your theme already uses H1 for the post title.

To insert a heading using Markdown, add hashes (#) corresponding to the heading you want to insert, followed by a space and your heading text. So, to insert a Heading 2 element (H2), you would write:

## My heading 2 title

This content will be converted to a Heading 2 element in the generated HTML. Press Enter to continue writing on the next line. If you want to insert a Heading 3 (H3) element, just add three hashes before the heading text, 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, which use numbered items, and unordered lists, which use bullet points instead of numbers for each item. For an unordered list, type a star (*), a hyphen/dash (-) or a plus sign (+), followed by a space before the first item's text. For example:

* The first item in my unordered list.

Pressing Enter automatically adds a list marker on the new line, so you can add the next item. Simply add your next item, then hit Enter again to create a third item, and so on. Once you've added all the items you want, pressing Enter on a blank item will end the list. The markers remain visible in the editor and appear as bullet points in the rendered content.

Inserting ordered lists works in exactly the same way, but instead of using a star or hyphen, start the list using 1. followed by a space. The editor continues the numbered list when you press Enter. Once you've added enough items, hit Enter on a blank item to end the list.

Adding Bold, Italic or Strikethrough Text with Markdown

Markdown can change your text to bold, italic or strikethrough by wrapping the text in the appropriate symbol: a star (*) for italics, two stars (**) for bold, and two tildes (~~) for strikethrough. To make a sentence bold, 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 provides visual formatting cues while you type, but the symbols remain part of the Markdown source. The location of the Tilde key depends on your keyboard layout; if you are having trouble finding it, you can copy the ~ character from this example.

Inserting Links with Markdown

Links are easy to insert into your content with Markdown. First, set the text of the link using square brackets [ ] around the words you want to turn into a link, and then put the destination URL in regular brackets ( ):

[link text](https://example.com/)

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

In addition to standard URLs, Publii supports internal links using a special placeholder syntax:

[Test link](#non-existing-post-with-id-7)

Internal links using #INTERNAL_LINK# are resolved when the full website preview or final site build is generated. The individual post preview and the Markdown editor's built-in preview do not resolve these placeholders. Use the link pop-up to select an internal destination without having to enter its ID manually.

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 Custom link, Post link, Page link, Tag link, Tags list link, Author link, Homepage link, Post index link, or File from File Manager.

This option defines what type of content you want to link to. Post, Page, Tag, and Author links allow you to link to a specific post, page, tag or author page on your Publii site. Tags list link points to the page listing your tags. Homepage link points to the homepage, while Post index link points to the page listing your posts. Custom link lets you enter a URL manually, 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 changes depending on the link type. For Post, Page, Tag or Author links, the second field contains a drop-down list where you can choose the destination. If you have many items in the list, start typing in the field to filter it.

For Custom link, use the second field to insert the URL that you want to link to. When linking to another website, enter the full address, including https://, to avoid creating a relative link by mistake.

For File from File Manager, the second field functions much like the post or page selector: it contains a drop-down list of files currently stored in Publii's File Manager. Again, you can filter the list by typing the name of the file you want to find.

Tags list link, Homepage link and Post index link do not require a second destination 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 the fields, click OK to insert the Markdown link.

Inserting Code

When we talk about inserting code into our content, we mean displaying code for readers, rather than running it in the browser. You can see it used throughout this page when demonstrating what to enter into the Markdown Editor to change the text styling. For example:

`This text will be displayed as code content`

There are two types of code content that can be entered: Inline Code and Code Blocks. The difference is important when you want to display a larger code example.

Inline Code, which is inserted as in the above example, is used for code within a paragraph, such as a filename, command or short expression. To insert it, add a backtick, also called a grave accent, before and after the code text:

Use the `index.html` file as your starting point.

For reference, the backtick is not an apostrophe, though it looks similar. Its location depends on your keyboard layout. You can copy the ` character from this example if you cannot find it.

A Code Block maintains formatting such as line breaks and indentation. This is particularly useful when displaying code that has multiple separate lines. To create a code block, add three backticks on a separate line above the text and another three on a separate line after it:

```
This is an example of a code block in Markdown.

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

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

Two backticks around text still create inline code; they do not create a multiline code block. They are useful when the inline code itself contains a single backtick.

You can also specify a language immediately after the opening three backticks:

```html
<p>This is a paragraph.</p>
```

To add syntax highlighting to code blocks on your published website, install and enable the Syntax Highlighter plugin. Use a language identifier that matches your code, such as html, css or javascript, after the opening backticks. Formatting in the Markdown Editor does not by itself add syntax highlighting to the published website.

Inserting Blockquotes

A Blockquote is a piece of text set apart from the surrounding content; useful for drawing attention to a quotation or including a quote from another source. Its appearance, including text size, borders or quotation marks, depends on your theme.

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 continues the blockquote by adding another > marker. Consecutive lines normally form one paragraph in the rendered blockquote, with wrapping determined by the available space:

> These two lines will appear
> as one paragraph in the blockquote.

To finish the blockquote, press Enter on an empty quote line, just as you would when ending an ordered or unordered list.

Inserting Images

Adding images to your content functions similarly to adding links in Markdown. First, put the image's alternative text in square brackets preceded by an exclamation mark ![ ]. Then, put the image URL in regular brackets ( ). For example:

![A view of the museum entrance](https://example.com/image1.png)

The text in square brackets becomes the image's alt text, rather than a visible caption. Use it to describe what the image shows in the context of your article.

Alternatively, you can drag and drop images from your computer directly into the Markdown Editor in Publii. It will automatically add the picture to the website files and insert the Markdown image reference. At this point, change the Image description placeholder to suitable alt text.

To add a visible caption, include quoted text after the image URL. Publii uses this text as the image's caption when generating the website:

![A view of the museum entrance](https://example.com/image1.png "The museum entrance on a sunny morning.")