Learning the Markdown syntax


March 01, 2022

  • Markdown

Overview - First things first, what is Markdown?

Markdown is a text-to-HTML conversion tool for web developers. Markdown allows you to write in plain text, then converts into a structured HTML format.

Markdown is everywhere. From Github repos to Reddit's comment system. I'm sure millions of online blogs as well. Considering this is a personal blog intended with the use of making many, I figured this would be a great excuse to learn how to use Markdown and it's syntax.

Markdown Syntax


Headings are created in Markdown with a set of hashtag (#) characters placed before the text for the heading. The number of hashes corresponds to the level of the heading, ranging from 1-6 hashtags (same to HTML header elements ranging from h1-h6)

Heading 1#

Heading 1

Heading 2##

Heading 2

Heading 3###

Heading 3

Heading 4####

Heading 4

Heading 5#####
Heading 5
Heading 6######
Heading 6
Note: Excuse the wonky styling. More infomation about this will be explained in the 'A Special type of Markdown' section below.


> Italics

To mark text in italics, add an asterisk (*) or underscore (_) before and after the text to be formatted.

> Bold

To mark text in boldface, add two asterisks (**) or two underscores (__) before and after the text to be formatted.

> Bold & Italics together

To emphasize text with both boldface and italics, use three asterisks (***) or three underscores (___) before and after the text to be formatted.

Block quotes

A block quote is a piece of text that is indented from the rest of the text. Below is lorem-generated text showing indentation.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Aliquam etiam erat velit scelerisque in dictum non. Semper feugiat nibh sed pulvinar proin gravida. Habitant morbi tristique senectus et netus et malesuada fames. In nisl nisi scelerisque eu. Quis hendrerit dolor magna eget est lorem ipsum dolor sit. Aliquet sagittis id consectetur purus ut faucibus pulvinar elementum. Non diam phasellus vestibulum lorem sed. Tristique sollicitudin nibh sit amet commodo nulla facilisi. Congue eu consequat ac felis donec et.

Block quotes are created by placing a greater-than sign (>) before each line in the quote. You can also add indentation by placing more than one greater-than-sign together.


> Unordered lists

To create an unordered list, place an asterisk (*), minus sign (-), or plus sign (+) followed by a space before each item

For example...

  • Reminder 1
  • Reminder 2
  • Reminder 3

To make a nested list, you simply add indentation to the nested items.

> Ordered lists

To create an ordered list, place a numeral followed by a period (.) and a space before each item in the list.

  1. Do this first
  2. Then do this
  3. Finally, do this


To add an image, first add an exclamation mark (!) followed by the alt text for the image in square brackets (e.g., ![Image alt text]) and the filename of the image in parentheses [e.g., (filename.jpg)].


Syntax for image above: ![Markdown](markdown-guide-og.jpg)


To create an external link in Markdown, write the link text in square brackets (e.g., [eBay]) followed by the URL in parentheses [e.g., (].

Example: If you click on this link, then you'll go to my portofolio home page.

Syntax for link above: If you click on [this link](, then you'll go to my portofolio home page.


> Inline code

Inline code refers to text in the middle of a sentence that is formatted in a different font (such as Monospace). It is used for things like variable and function names. It can also be used to print text literally without having to escape special characters.

To mark text as inline code, enclose it in backticks (`).

Example: The function named sum should return an integer.

> Code Block

I think the best place to start (considering this blog post is a tutorial as well) is with code blocks. There's going to be many code blocks within this post, so let's show how to get it done.

If I wanted to display some code, for example...

function saySomethingToTheBlog(something) {

saySomethingToTheBlog("Hello Blog!");

... I would inital that by simply input three backticks (```) before & after my code.

You can also preface what syntax you're writing your code in by specifying a language next to the backticks before the fenced code block.

    ```javascript (language goes here)
    // code

A Special type of Markdown

If you look closely up top in the 'Headings' section (let's be honest, its impossible to miss), you'll see extremely unpleasant styling. That's because even though blog is written in Markdown, it uses a special type of Markdown. What is being used is called "MDX." This whole site was made using the static-site generater Gatsby. GraphQL has many plugins that make developing a breeze, one being called 'gatsby-plugin-mdx'. Mdx is a combination of JSX and Markdown that make developing React-based blogs easier.

Mdx lets you import and export components like you would regularly in a React app, as well as giving you the option to style elements inside the MDX file. React will then take that MDX file and render it as a component. Well, in order to style my blogs in the way I enjoy, I have to override default Markdown styling (hence why you get horrible styling for some elements above.) But being able to combine Markdown & JSX is a huge plus React blogs!