Introduction to Markdown

A general problem developers and writers face while creating written content and documentation is in editing, formatting, and sharing text-based content across different platforms.

Markdown files are incredibly versatile, supported across a wide range of platforms, allowing you to view, edit, and share your content without any compatibility issues. As a text formatting tool, Markdown is not only powerful but also easy to learn and master.

This course explores the unique benefits it offers, and what sets it apart from other text editors. You’ll start with the fundamentals, learning about various Markdown tools and how to set them up. From there, you’ll master the basic syntax and formatting, enabling you to create well-structured, visually appealing content with ease.

Course Overview#

In this course you will learn the following;

• Definition of markdown, its history, and importance in content creation
• Markdown syntax, from the basic syntax to advanced syntax, markdown tools, and version control
• Practical applications, learn how to use markdown in writing documentation, blogging, collaborative editing projects, and version control
• Best practices, Tips, and guidelines for consistent formatting and style of markdown files.

What is Markdown?#

Markdown is a lightweight markup language designed to format plain text effortlessly. Created by John Gruber and Aaron Swartz in 2004, it’s become a go-to tool for anyone looking to add structure and style to their writing without the complexity of traditional markup languages.

Using Markdown is as simple as adding specific symbols and characters—like asterisks (**), hash signs (#), brackets (()), and commas—directly into your text. These symbols act as commands, telling Markdown how to format the content.

With Markdown, you can easily make your text bold, create headings and subheadings, emphasize key points, organize information into ordered or unordered lists, and even embed images, links, and videos—all with just a few keystrokes.

The image below provides a quick overview of the various Markdown syntax options to get you started.

Uses of Markdown.#

It is widely used across various fields and platforms due to its simplicity, readability, and compatibility with many tools and systems.

Below are some common uses of Markdown:

1. Technical Documentation: Markdown is favored for writing technical documentation because it keeps the content clear and readable while allowing easy formatting. It is often used in README files, software documentation, and developer guides.

2. Web Content Creation: Many static site generators like Jekyll, Hugo, and Gatsby use Markdown as the primary format for creating web content. Its straightforward syntax helps quickly generate web pages without needing complex HTML.

3. Blogging: Bloggers often prefer Markdown for writing posts because it lets them focus on the content without worrying about intricate formatting. Blogging platforms like Ghost and Jekyll fully support Markdown.

4. Note-taking: Applications such as Obsidian, Notion, and Simplenote enable users to take notes in Markdown. This format makes organizing and exporting notes easy, providing a flexible way to manage information.

5. Writing for Publications: Some online publications and content platforms accept or prefer Markdown-formatted submissions. Its minimalistic structure ensures the focus remains on content, making it ideal for clean and readable articles.

6. Documentation Repositories: Markdown is extensively used in repositories on platforms like GitHub, GitLab, and Bitbucket. It’s commonly seen in README files, contributing guides, and project wikis, making collaboration and documentation management more efficient.

7. Creating Presentations: Tools like Reveal.js, Marp, and Deckset enable users to create presentations with Markdown. This approach lets users focus on the content, producing clean and effective slides with minimal effort.

Advantages of Using Markdown#

Markdown offers several key advantages, making it a popular choice for writers, developers, and content creators across various fields. Below are some of the primary benefits:

1. Easy to Learn and Use: One of Markdown’s biggest strengths is its simplicity. The syntax is straightforward to grasp, making it accessible even for beginners. Unlike more complex markup languages, mastering Markdown requires minimal time and effort, allowing users to create well-structured documents quickly.

2. Properly Structured and Formatted Content: With Markdown, creating well-organized content is simple. You can easily add headings, create lists, and construct tables while maintaining a clear and consistent structure throughout your document. This results in content that is not only readable but also professionally formatted.

3. Cross-Platform Compatibility: Markdown is highly compatible with various devices, platforms, and software applications. Whether you’re working on a desktop, tablet, or smartphone, or using different operating systems, Markdown ensures that your content remains consistent and accessible across all platforms.

4. Versatile Application: Markdown is used extensively in UX writing for websites, technical documentation, and note-taking. Its flexibility allows it to adapt to various writing tasks, making it a valuable tool for content creators, technical writers, and developers.

5. Extensible with Easy-to-Use Extensions: Markdown can be extended with various plugins and tools that add functionality, such as support for additional formatting options, diagram creation, and more. These extensions are generally easy to navigate and use, allowing you to customize your Markdown experience to suit your needs better.

Markdown vs WYSIWYG (What you see is what you get) editors.#

When creating content, you might use either Markdown or a WYSIWYG (What You See Is What You Get) editor.

Markdown#

Pros:#

• Simple and Clean: Markdown is straightforward, using just a few symbols to format text.

• Portable: Since it’s plain text, Markdown files work well across different platforms and tools.

• Great for Collaboration: Markdown integrates smoothly with version control systems like Git, making it ideal for team projects.

Cons:#

• Limited Styling: You can’t easily change fonts or colors without adding extra code.

• Learning Required: There’s a bit of a learning curve for new users.

• No Instant Preview: You won’t see the final look until you preview the document separately.

WYSIWYG Editors#

Pros:#

• User-Friendly: These editors are easy to use, with buttons for formatting that don’t require learning any special syntax.

• Real-Time Preview: You can see how your content will look as you create it.

• Advanced Options: WYSIWYG editors offer more styling and formatting choices without needing to code.

Cons:#

• Can Be Overwhelming: The many options can lead to inconsistent styles and make things complex.

• Heavier Output: They often produce bloated code, which can slow down web pages.

• Less Code Control: The automatic code generation can sometimes be messy or hard to clean up.

Which to Choose?#

• Markdown is best for those who need simplicity, portability, and version control.
• WYSIWYG Editors are ideal for users who want ease of use, advanced styling, and real-time feedback.

The image above is an example of a WYSIWYG editor called Google Docs. There you see the toolbox with several options to change your text.

Examples of WYSIWYG editors are;#

Microsoft Word, WordPress, Google Docs, TinyMCE, Adobe Dreamweaver. Using this software allows you to make changes directly by clicking on buttons to format text and changes are visible immediately. These two editors share some similarities and also have their unique differences.