Odafe's View
Beginners guide to Markdown

Beginners guide to Markdown

Odafe Alaiya's photo
Odafe Alaiya
·

8 min read

Table of contents

The ability to present your thoughts and ideas clearly and concisely is important regardless of what industry you work in. Luckily, there are a host of tools and technologies that assist in helping craft good text content. Enter Markdown – a versatile yet unassuming markup language that has become a staple for writers, programmers, and content creators of all kinds. If you're new to the realm of Markdown, fear not; this guide is designed to be your compass on a journey toward mastering this user-friendly markup language.

What is Markdown?

Markdown is a lightweight markup language that simplifies the process of formatting text for the web and other mediums. It was created by John Gruber and Aaron Swartz in 2004 as a way to write content that can be easily converted into HTML and other formats without requiring extensive technical knowledge. It is particularly popular among writers, bloggers, programmers, and anyone who needs a simple and efficient way to format text for the web.

Advantages of Using Markdown

1. Simplicity and Readability: Markdown uses a straightforward syntax using plain text characters. This simplicity makes it easy to learn and use, allowing you to focus on the content itself rather than complex formatting codes.

2. Platform Independence: Markdown is platform-independent. You can create Markdown documents on any device using a text editor or a code editor, and these documents can be easily viewed and converted into various formats on different platforms. This consistency ensures your content's accessibility and longevity.

3. Quick Learning Curve: Markdown has one of the easiest syntaxes. This means you can learn it in a short amount of time. The syntax is intuitive, resembling the formatting you might already use in emails or text messages. This quick learning curve encourages adoption for those who are non-technical users.

4. Wide Adoption: Markdown has gained immense popularity and is supported across a multitude of platforms, including blogging systems like WordPress, collaboration tools like GitHub, and content management systems. This makes Markdown a valuable skill that can be applied in many contexts.

5. Speed and Efficiency: Creating content in Markdown is fast and efficient. With a few simple characters and other formatting elements. This in return allows its users to craft documents with simplicity, efficiency and speed.

6. Version Control: When using Markdown in collaboration with version control systems like Git, changes made to Markdown files are easy to track. This makes it simpler to collaborate on projects, review changes, and maintain a clear record of edits.

Getting Started with Markdown

Markdown works in a variety of text editors and code editors. For the sake of this article, we shall be focusing on using markdown in code editors, particularly VS Code. Although the same syntax can be followed in text editors.

  1. Firstly in your VS Code create a folder (You can name it whatever you want). In that folder create a file called markdown.md

  2. Navigate to the top right section of your VS Code file and click on the preview button to get a preview of your result side-by-side.

Basic Formatting in Markdown

Here are some of the basic syntaxes for formatting text in Markdown.

  1. Headers: Headers are used to indicate different levels of Heading in your document. To create Headers in Markdown use the # symbol followed by a space then your Header text. Note that the number of # symbols determines the levels of your Heading. See the example below.

     # Heading
 ## Heading
 ### Heading

  2. Emphasis: You can add emphasis to your text by making it bold or italic. To make text bold, enclose it in double asterisks ** or double underscores __. To make the text italic, enclose it in single asterisks * or single underscores _.

    Example:

     This is the **Bold Text** 
 This is *italics*

  3. Lists: Markdown supports both ordered (numbered) and unordered (bulleted) lists. To create an ordered list, start each item with a number followed by a period. To create an unordered list, use either an asterisk *, plus +, or hyphens -.

    Example:

     Ordered List:
 1. First item
 2. Second item
 3. Third item

 Unordered List:
 * Item 1
 * Item 2
 * Item 3

  4. Links: You can create hyperlinks in Markdown using square brackets [] for the link text and parentheses () for the link URL.

    Example:

     [Visit Odafe's Website](https://www.odafe.vercel.app)

  5. Images: Inserting images is similar to creating links, the only difference being an exclamation mark ! in front of the square brackets. The alt text in the square brackets is used to describe the image for accessibility.

    Example:

     ![Alt text](image-url.jpg)

  6. Blockquotes: Blockquotes are used to display quote texts. To create this simply start the line with the > symbol followed by the text you want to be quoted.

    Example:

     > This is a quote by Odafe

    The output looks like this:

    This is a quote by Odafe

  7. Horizontal Rule: You can add horizontal separators by simply using three underscores _ .

    Example:

     This is a regular text
 ____
 This is more regular text

These are the foundational elements of basic formatting in Markdown. By mastering these concepts, you'll be able to create well-structured and visually appealing content, whether you're writing a simple note or crafting a more complex document.

Advanced formatting in Markdown

Markdown also offers additional functionality in cases where you might need to add more intricate elements to your document. Some of these formatting options are:

  1. Code Blocks and Inline Code: You can easily add code blocks to your file by starting your code blocks with three backticks (```) followed by the language your code block is written in. Inline codes are added by wrapping the code snippet in single backticks.

    Example:

     This is a HTML element `<div>Hello World</div>`

 ```javascript
     function myFunction() {
         console.log("Hello world!")
     }

  2. Task Lists: Task lists are useful for creating to-do lists. To create a task list, use square brackets with an "x" for completed tasks and a space for incomplete tasks.

    Example:

     - [x] A complete task
 - [ ] An incomplete task

  3. Emojis: There are two ways to add emoji to Markdown files: copy and paste the emoji into your Markdown-formatted text, or type emoji shortcodes.

  4. Strikethrough Text: To strike through text, use double tildes (~~) around the text you want to strikethrough.

    Example:

     This is a ~~Strikethrough~~ text.

  5. Escape Characters: If you need to display characters that have special meaning in Markdown, you can escape them using a backslash (\).

     To display a literal asterisk \* use a backslash before it.

  6. Superscript and Subscript: To create a superscript, the superscript text is wrapped in two ^ symbols.

    To create subscript text, the text is wrapped in two ~ symbols.

    Examples:

     This is how a superscript is written: X^2^ 
 This is how a subscript is written: H~2~O.

  7. Tables: To create tables in Markdown follow these steps:

    • Start and end each row with a pipe symbol (|).

    • Separate each column with a pipe symbol (|).

    • Use three or more hyphens (---) to create column headers.

    | Syntax      | Description |
    | ----------- | ----------- |
    | Header      | Title       |
    | Paragraph   | Text        |

Rendered output looks like this:

Creating tables in markdown manually might be difficult so you might want to opt for a table generator.

  1. Highlight: You can highlight Important words in your document by using two equals signs (==) before and after the word(s).

    Example:

     This highlighted word is ==Bee==

    This is what the output looks like:

  2. Footnotes: Footnotes are a way of adding notes and references at the end of your document without cluttering the main body. To create a footnote reference, add a caret symbol (^) and a unique identifier (usually numbers or words) inside brackets ([^1]). Identifiers cannot contain spaces or tabs. In the output, footnotes are numbered sequentially.

    Example:

     This is an example sentence with a footnote[^1].

 [^1]: This is the content of the footnote.

    The output:

You can learn more about advanced formatting in Markdown here.

Real-world Applications on Markdown

Markdown has gained a lot of popularity among the software developer and programming community. Notably, it has found a pivotal role within version control platforms, serving as a comprehensive and accessible means to explain the essence of a codebase.

By employing Markdown as a conduit for describing the intricacies of one's code, developers create a harmonious blend of clarity and context. This practice extends a helping hand to those who stumble upon their code repository, facilitating a swift and profound grasp of the project's overall purpose and nuances. In this manner, Markdown stands not only as a formatting tool but as a powerful communicator, bridging the gap between intricate coding endeavors and their profound real-world implications.

Conclusion

Remember, Markdown isn't just a tool; it's a bridge that connects your thoughts to a global audience, enabling your voice to be heard with clarity and impact. Its compatibility with various platforms, its simplicity, and its adaptability ensure that your journey with Markdown is not confined to this guide, but continues as you explore new ways to express yourself and your ideas.

Resources

markdowntext formattingbeginner