May 1, 2024

A Beginner's Guide to Markdown

Justin Golden

If you’ve ever come across README files, blog posts, or discussions on platforms like Reddit or Discord, you might have noticed a certain formatting style. This is Markdown—a lightweight markup language designed for easy readability and writing on the web. Let’s dive into why Markdown is useful and where it’s commonly used.

What is Markdown?

Markdown is a plain text formatting syntax that allows you to add formatting elements to plain text documents. It was created by John Gruber and Aaron Swartz in 2004 with the goal of enabling people to write using an easy-to-read and easy-to-write plain text format, which can then be converted into structurally valid HTML.

Why Use Markdown?

Markdown is useful for a variety of reasons:

• Simplicity: Markdown syntax is straightforward and easy to learn, making it accessible to beginners.
• Readability: Markdown documents are easy to read even in their raw form, which makes them ideal for collaboration and documentation.
• Portability: Markdown documents can be viewed in any text editor, and most platforms and tools support Markdown rendering, making them highly portable.
• Versatility: Markdown supports basic formatting elements such as headings, lists, bold and italic text, links, images, and code blocks, making it suitable for a wide range of writing tasks.

Where is Markdown Used?

Markdown is widely used across various platforms and contexts, including:

• Documentation: README files in software projects often use Markdown for formatting project information, installation instructions, and usage guidelines.
• Blogging: Many blogging platforms support Markdown, allowing bloggers to focus on writing content without worrying about complex HTML formatting.
• Discussion Forums: Platforms like Reddit and Discord allow users to format their posts and comments using Markdown, enhancing readability and organization.
• Note-taking: Markdown is popular among writers, researchers, and students for taking notes and organizing information in a structured yet simple format.
• Messaging Apps: Some messaging apps and productivity tools support Markdown for formatting messages and documents.

Basic Markdown Syntax

Here are some basic Markdown syntax elements:

• Headings: Use # for headings (e.g., # Heading 1, ## Heading 2).
• Lists: Create ordered lists with numbers (1., 2., etc.) or unordered lists with dashes (-) or asterisks (*). You can use - [ ] and - [x] to denote unchecked and checked checkboxes in your list.
• Bold and Italic: Use double asterisks (**bold**) for bold text and single asterisks (*italic*) for italic text.
• Links: Create links with [link text](URL).
• Images: Embed images with ![alt text](image URL).
• Code Blocks: Use backticks (`) for inline code and triple backticks ( ```) for code blocks.

Formatting Code

If you use triple backticks, leave the rest of that line blank. You can also write the language you are using if you want syntax highlighting, for example, ```html and then write your html between the triple backtick lines. Use md instead of html to format as markdown. You can write js, ts, css, json, and plenty of others depending on the support of the markdown engine you’re using.

Others

You can also create tables and other complex structures, and there are some variants that allow strikethrough (~), allow underscores (_) for bold and italic, and more. The above syntax should get you through 99% of use cases.

Check out Markdown Guide and Common Mark for a good break down, Daring Fireball for a more in depth guide. Try MarkdownTutorial.com for a tutorial walk through.

Conclusion

Markdown is a versatile and easy-to-use markup language that simplifies the process of formatting text for the web. Whether you’re writing documentation, blogging, or participating in online discussions, Markdown can help you communicate your ideas effectively while maintaining readability and clarity. So go ahead, give Markdown a try, and unleash your creativity in writing!

Aside

If you want to render triple backticks in a code line (such as what I needed for this article 😅), then you can write:

`````