Working with Markdown requires some planning, but it can be a game changer for authors looking to streamline their workflow.
It's not difficult to learn the Markdown language and find a good editor, but it might require some guidance to get the most out of the language in documentation projects.
Markdown comes in a few different flavors, but the tips included here span the various types. Be sure to research what makes a Markdown flavor unique so you, as an author, can make the most of its features.
Here are a few common Markdown variations:
CommonMark. A set of detailed rules and extensibility for a consistent specification.
GitHub Flavored Markdown. A specification that supports tables, lists and autolinking for GitHub documentation.
Markdown Extra. Additional Markdown features, including tables, footnotes and fenced code.
13 Markdown tips and tricks
Markdown is a powerful tool in any writer's utility kit. Start by getting into the habit of building good documents and understanding the fundamental Markup instructions. It's also essential to find and get comfortable with a good editor that includes a preview feature. And while Markdown is wonderful, it's only suitable for certain kinds of documentation, so don't mix it with resources created in Word or similar word processors -- use the right tool for the job.
If Markdown is the right tool for your project, use these 13 tips to build your skills.
1. Set a foundation
As with any tool, take the time to learn the basics. Make sure you identify how to use the following formatting instructions:
Markdown is a powerful tool in any writer's utility kit. Start by getting into the habit of building good documents and understanding the fundamental markup instructions.
Bold. Use two asterisks or two underscores on each side of a word to bold it.
Italics. Use one asterisk or one underscore on each side of a word to italicize it.
Bold and italics. Use three asterisks or three underscores on each side of a word to bold and italicize it.
Horizontal rule. Use three asterisks, dashes or underscores on a line without other characters.
Ordered list. Use 1 followed by a dot to create a numbered bullet point. Markdown automatically increments the numbers.
Unordered list. Use a single dash to create a bullet point in an unordered list.
Headers. Use hash characters to define headers. A single # represents an H1 header, ## is an H2 header, ### is H3, etc.
A few minutes of learning the fundamental markup instructions translates into great efficiency and speed -- an important part of creating documentation with Markdown.
2. Provide a table of contents
Use a table of contents for larger documents to enable readers to jump to the content area they need without having to scroll through the entire body of text. Each table of contents entry contains a link to the related section header. This makes the document easier for you to work with and readers to consume.
Use the following steps to create a table of contents:
Create a list of header entries -- probably at the H1 or H2 levels only.
Add a link to each header entry using this syntax: [Header Text](#section-title).
The #section-title string should be the heading's text in lowercase. Replace any spaces with dashes.
For example, if you have an H2 header named "Markdown Examples," the table of contents link would look like this:
[Markdown Examples](##markdown-examples)
A reader clicking on the link immediately jumps to that section of the document. A more detailed example of a table of contents in Markdown is shown in Figure 1.
Figure 1. The author uses linking and heading syntax in the left pane to create the table of contents shown in the right pane.
3. Build the structure
Structure your document correctly. Begin with an outline that organizes your primary points and identifies secondary content, and create a header structure that reflects this document design.
Create headers by using one or more hash characters followed by a space and the header text. Markdown recognizes many header layers but most documents only need levels H1, H2 and H3.
It's also a good idea to create a template for projects you work with regularly.
4. Read the empty lines
Use empty lines properly. Markdown relies on empty lines for some of its formatting instructions. Place empty lines after headers, between paragraphs and between list items. These lines become more important with advanced features, such as expandable text.
5. Keep a list
Adding lists to a Markdown file can make its contents easier to consume. Markdown offers ordered and unordered lists. Use the 1. characters to create an ordered list. Markdown automatically increments the step numbers in the output. The dash character creates the bullet points making up the unordered list.
The following code creates an ordered list:
1. First item
1. Second item
1. Third item
This code generates an unordered list:
- First item
- Second item
- Third item
Indent additional times to create subpoints.
Make your basic list into an interactive checklist by placing [] after the list characters. The output displays checkboxes that readers can toggle on and off. Note that not all Markdown flavors support checkboxes. Following is how to format a checkbox:
- [] Checkbox
See Figure 2 to for the syntax to create ordered lists, unordered lists and checklists as they would generally appear in a Markdown editor.
Figure 2. Three different list types -- ordered, unordered and checklist -- in the right pane and their corresponding syntax in the left pane.
6. Fence in your code
Many technical writers use Markdown on coding projects, which means delineating code blocks as part of a demonstration or explanation. Inline code uses three backtick characters (```) on each side of the code snippet. The result looks like this:
The ```print('Hello World')``` code prints "Hello World" in a Python environment.
However, a code block is more effective for multiple lines of code. Create a fenced code block by adding three backtick characters (```) just above and just below the lines of code.
For example, format this simple two-line code block with Markdown like this:
```
# Print "Hello World" using Python
print('Hello World')
```
See Figure 3 for an example of the syntax for an embedded code block as it would appear in a Markdown editor.
Figure 3. The author writes the syntax for inline and fenced code snippets on the left and the result is printed in the preview pane on the right.
7. Add links to your document
Markdown offers a lot of flexibility for linking to other documents or websites. Leaving bare URLs -- such as "http://www.techtarget.com" -- is frowned upon. Add a link to existing text instead. Enclose the text in square brackets [] immediately followed by parentheses containing the URL and a descriptive field that increases search engine optimization.
This code snippet demonstrates the idea:
See the [TechTarget](http://www.techtarget.com "TechTarget homepage") site for more Markdown content.
Figure 4 demonstrates how this example would look in a Markdown editor.
Figure 4. The author uses linking syntax in the left pane of the editor to link a piece of text, as shown in the preview pane on the right.
Links can also point to other parts of the document, as seen in the table of contents section.
8. To edit is divine
One of the most useful tips for working effectively in Markdown is to find a good editor that offers the features you need. Some users prefer online editors, such as StackEdit or Minimalist Online Markdown Editor.
Other authors prefer local text editors, such as Typora or Ghostwriter. Still others use the Microsoft VS Code editor for their Markdown projects. It offers extensions and a handy preview option.
This author is partial to the Vim text editor. Various incarnations of it support Markdown features or are extensible. For example, there's the markdown-preview.nvim plugin for the popular NeoVim application, which allows users to preview Markdown in a modern browser.
9. Learn the shortcut to success
Once you take the time to select a Markdown editor, be sure to learn its features and shortcuts. These capabilities make working in Markdown far easier by helping with formatting and updating the preview as you type, for example.
In addition, explore the editor's extensions. Many text and code editors support customizations, plugins and extensions that simplify working with Markdown.
10. Preview everything
Use the editor's preview feature as you work in Markdown. It allows you to correct mistakes right away and ensure your document is structured correctly. Preview is one of the most useful features of any editor. Figure 5 shows the coding pane and preview pane side by side.
Figure 5. Preview mode makes it easy to see your rendered Markdown. The coding pane is on the left and the preview pane is on the right, showing what the code will look like when rendered.
11. Take a picture
A picture may be worth a thousand words, but adding an image to your Markdown document will only cost you a few. The syntax for adding an image is: . You can reference a local image, an image repository or even an online site. Effective alt-text is useful for screen readers and might help your search engine optimization results.
Suppose you have a picture of your favorite guitar stored at ~/articles/images/guitar.jpg and you want to include it in your document. You could type the following Markdown link:
Figure 6 shows how Markdown displays an image rendered in a browser after using the image syntax in the Markdown file.
Figure 6. An image rendered in a browser with the code for inserting that image in the Markdown file behind it.
12. Keep it portable
Keep your markdown documents as simple text files rather than importing them into a word processor. Applications like Microsoft Word add extra formatting instructions behind the scenes that will likely interfere with Markdown rendering.
This author is a proponent of authoring in simple text editors but it's even more vital with Markdown. File portability is one of Markdown's greatest strengths and benefits, so don't weaken it by inadvertently adding nonstandard formatting.
13. Create a cheat sheet
Create your own Markdown cheat sheet containing the features you need but struggle to remember. Add in the idiosyncrasies of your selected Markdown flavor. You could even add a few HTML tags to extend Markdown's capabilities if needed.
My current projects include developing labs using Markdown, so I generally work with Markdown daily. However, between projects, I may go months without using it. A cheat sheet is a great reference to help me get back into the habit of using Markdown.
Damon Garn owns Cogspinner Coaction and provides freelance IT writing and editing services. He has written multiple CompTIA study guides, including the Linux+, Cloud Essentials+ and Server+ guides, and contributes extensively to TechTarget Editorial, The New Stack and CompTIA Blogs.
Dig Deeper on Software development team structure and skills
