A Technical Writer's Guide To Markdown
A guide to getting started with Markdown, an essential tool in a technical writer's arsenal.
Markdown is a way for developers and technical writers to write content for the web without having to use HTML. It has become an essential tool for technical writers as it is widely used by the technical community because of its simple syntax; and it allows you to create and publish documentation in plain text, while it renders your doc to HTML for the Web.
This guide introduces you to the basics of Markdown as a technical writer; giving an overview of what it is, why it is important and widely used, tools you can use to practice, as well as basic Markdown syntax and commands that you'll get to use regularly in your documentation as a technical writer; and are useful in any environment from GitHub to an integrated development environment (otherwise known as an IDE).
What Is Markdown?
Markdown is a simple plain-text markup language that is easy to learn, easy to use, and was designed to help non-coders easily write and format content for the web. It was developed by John Gruber in 2004 as a simple markup language that is easy to read in its source-code form and an alternative way to write content for the web without having to deal with the messiness of HTML tags. Markdown is heavily focused on being plain and readable, allowing you to create and format text easily without having to deal with formatting menus and toolbars present in most word processors.
While Markdown brings ease to writing for the Web, it is also not a perfect HTML alternative, as the original Markdown syntax does not contain formatting for other HTML elements you might need - such as tables; and can also be a bit ambiguous. This has led to the creation of different Markdown variants to solve these issues:
CommonMark is focused on standardizing Markdown to make it less ambiguous.
MultiMarkdown adds new syntax for tables, footnotes, and citations.
GitHub Flavored Markdown (GFM) is used when creating documentation on GitHub.
Pandoc extends Markdown for multiple outputs beyond just HTML, while also supporting other features like document metadata, footnotes, tables, superscript, and superscript.
There are Markdown editors in some web services and IDEs that support the syntax of some of these variants; with some of them using their version of Markdown. However, this guide is focused on the original Markdown syntax, along with a few GitHub Flavored Markdown extras.
Why Use Markdown?
Markdown is the favoured language for writing content in the developer community, and it solves many problems technical writers deal with when collaborating on and publishing documentation. It is an ideal format for writing READMEs, API documentation, user guides and tutorials, release notes, and more. Markdown is also integrated in various version control tools and allows developers as well as other non-technical stakeholders to still review the formatting; following the Doc-as-code philosophy.
Here are some other benefits of using Markdown:
Lightweight - Markdown files are lightweight, as they contain just plain text with simple formatting marks. They are usually much smaller in size and faster to load than heavy word processing files or complex HTML/CSS layouts.
Readable - Being plain text makes a typical Markdown file less messy and very readable before being converted to HTML.
Writable - Markdown syntax is easy to learn and create with almost any basic text editor.
Portable - Markdown documents, being just plain text, can be opened on any device.
Universal standard - Markdown is a universal standard for writing in the technical community, is extremely popular, and is supported on most platforms, sites, and tools.
As a technical writer, learning Markdown is non-negotiable and should be a top priority. Plus it's easy too!
Starting with Markdown
One of the best things about Markdown is that it is widely used. Many text editors that have built-in support for it; no matter what operating system you use. In addition to this, collaboration and version control tools (such as GitHub) also have Markdown support so that technical writers can create documents in the same space where developers create code.
That being said, here are some options you can consider as you start learning Markdown:
Plain text editors: Apps like Visual Studio Code, Sublime Text, Atom, Vim, or Notepad++ work great for composing Markdown. Most of them also have preview extensions that show you the rendered HTML live as you type.
Static site generators: Static Site Generators (SSGs) like Jekyll and Hugo allow writing Markdown and publishing static sites or documentation easily.
Version control systems: Markdown files work seamlessly with Git and are supported on version control tools like GitHub and GitLab.
Markdown for Mobile: Many writing and note-taking apps for mobile devices (iOS and Android) support basic Markdown, and some of them act as specialized Markdown editors for mobile devices.
Basic Markdown Syntax
Basic syntax in Markdown involves just a few special characters that can be combined with text content to produce different kinds of formatting. Here are the most common Markdown commands/syntax you'll encounter and use frequently as a technical writer:
Headings
Headings in Markdown can be created by prefixing the heading text with hashtags (#), like this:
# This is a heading
## This is also a heading
### What about this? It's a heading too!
Output:
This is a heading
This is also a heading
What about this? It's a heading too!
The number of hashtags you will use determines the heading level, and is equivalent to <h1> to <h6> tags in HTML
Paragraphs
Creating paragraphs in Markdown is similar to how you would create paragraphs using normal text processors like Word. All you have to do is leave a blank line between two sections of text by leaving two spaces at the end of a line before using the enter key, which creates a new paragraph for the section below.
For example:
This is a paragraph being created.
This is also another paragraph being created.
This is a paragraph being created.
This is also another paragraph being created.
Using Bold and Italics for emphasis
Just like in normal word processors, you can use bold and italic features in Markdown to demonstrate emphasis on a text, like this:
*This text is in italics*
_This text is also italicized_
**This text is bold**
__This text is also bold__
Output:
This text is in italics
This text is also italicized
This text is bold
This text is also bold
Italics are created with a single asterisk or underscore attached to the beginning and end of the word or phrase, while bold features are created with double asterisks or underscores attached.
Line Breaks and Separations
Sections of a document can be easily separated in Markdown by using three or more hyphens, asterisks, underscores, or equals signs to create horizontal rulings on a line, with blank lines on either side of the sections you want to separate:
Living is simple
****
# A Brief Bio
Lots of text.
----
## My name Is Fury
Some more text.
Output:
Living is simple
A Brief Bio
Lots of text.
My name Is Fury
Some more text
Line Breaks
The Name
\
\
Of The Wind
The name
Of the wind
Dealing With Lists
Lists are another important structural element. With Markdown, you can create both ordered and unordered lists
To create unordered or bulleted lists, just use -, *, or + before each item. You can also create nested lists by indenting lines by 2 spaces.
- Item 1
- Item 2
- Nested item 1
- Nested item 2
To create ordered lists in Markdown, use numbers followed by a period (.) for each item.
1. Item 1
2. Item 2
1. Nested item 1
2. Nested item 2
Links
To create a link, add the link text in brackets, i.e [link text] and the URL in parentheses () - without spaces; like this:
[Visit My Blog](technicallyjames.hashnode.dev)
Output:
You can also add a title attribute for the link by adding it in quotes after the URL.
Images
Adding an image in Markdown is similar to links. work like links. However, for images, you add an exclamation mark, followed by the alt text in brackets (for accessibility), and the path or URL to the image in parentheses.
An example:
As with links, you can optionally add a title after the URL in the parentheses.
Quotes
You can create blockquotes (for quote content) using the greater than sign (`>`) at the beginning of each quoted paragraph.
> "This is a blockquote."
Albert Einstein said:
> "I am enough of the artist to draw freely upon my imagination. Imagination is more important than knowledge. Knowledge is limited. Imagination encircles the world."
"This is a blockquote"
Albert Einstein said:
"I am enough of the artist to draw freely upon my imagination. Imagination is more important than knowledge. Knowledge is limited. Imagination encircles the world."
Code
Code can be displayed in two ways:
Inline code, which can be done with single backticks (`) around it, like this:
Creating `inline code` is easy. Just add `a single backtick`.
Output:
Creating inline code is easy. Just add a single backtick.
Code blocks, which can be created by ‘fencing’ the code with three backticks, indicating the language you're dealing with.
E.g.
```python
print("Hello, World!")
Here's the output:
print("Hello, World!")
Tables
While tables aren't part of the original Markdown syntax, it is included in most variants, including GFM. They can be created using pipes `|` to divide columns and rows, with at least three dashes for each column to indicate a header.
This is a table:
First col | Second col | Third Col
--- | --- | ---
*I am* | a Markdown | **table**
1 | 2 | 3
Output:
| First col | Second col | Third Col |
| I am | a Markdown | table |
| 1 | 2 | 3 |
Diving Deeper: Further Resources
Now that we have covered the Basics of Markdown in this simple guide, here are a few resources you can check out if you want to dive deeper and go advanced with this simple markup language.
Conclusion
As a technical writer, mastering Markdown is a basic skill for creating technical documentation today. This is because Markdown has become a standard format for writing any form of content for the web; as it is lightweight, simple to learn, easily usable, and easily readable.
If you've made it to the end of this guide, congratulations 👏🏾! This guide has provided an overview of all you need to get started with using Markdown as a technical writer. The more you learn Markdown, the more you become used to using it.
What are you waiting for? Get started!