Skip to content

1. Markdown

Have you ever wanted to make your writing look more organized and professional? Markdown is like a secret code that helps you do just that! It's a simple way to format and structure text that works on many websites, apps, and social media platforms. Everything you see on this web page is written in markdown.

1.1 Markdown and HTML?

Markdown is a lightweight formatting language created to make writing for the internet easier. To understand why it's so useful, let's first understand what HTML is.

HTML (HyperText Markup Language) is the standard language used to create websites. It uses "tags" like <h1> for headings and <p> for paragraphs. Think of HTML tags as labels or roles in a play or movie production. Just like how a movie has a director, actors, set designers, and scriptwriters—all serving specific functions to create the complete story -- HTML tags define the role and purpose of each element on a webpage. For example

  • The <p> tag identifies text as a paragraph, telling browsers "this is a complete thought," not just "make this look like regular text."
  • The <h1> through <h6> tags don't simply mean "make this text big" but rather establish a hierarchy of importance - like the difference between a movie's title, chapter headings, and scene descriptions.

When browsers and search engines read your HTML, they're not just learning how to display your content—they're understanding what each piece of content means and how it relates to other pieces. This understanding allows screen readers to properly convey information to people with visual impairments, search engines to properly index your content, and various devices to adapt your content appropriately.

<h1>This is a heading</h1>
<p>This is a paragraph.</p>
<a href="https://example.com">This is a link</a>

While HTML is powerful, it can be cumbersome to write, especially for beginners. You need to remember to close every tag, and the syntax can get complicated.

This is where Markdown shines! Markdown was designed to be:

  1. Easier to write and read than HTML
  2. Convertible to HTML (behind the scenes)
  3. Accessible to everyone, not just web developers

Instead of using complex tags, Markdown uses simple symbols that feel more natural. The same HTML example above would look like this in Markdown:

# This is a heading

This is a paragraph.

[This is a link](https://example.com)

Much cleaner, right? Markdown is better than HTML in many cases because:

  • It's faster to write
  • It's easier to read in its raw form
  • It's less prone to syntax errors, no missing closing tags </p>
  • You don't need to understand web development to use it

Imagine you're writing

  • Notes for school
  • Posts on Reddit or Discord
  • A story you want to share online
  • Instructions for a project
  • A journal or blog

Markdown can make all of these look more organized and easier to read. Plus, many websites and apps already support it, so it's a super useful skill to have.

1.2 Basics

1.2.1 Headings

Headings help organize your writing into sections, like chapters in a book. To create headings, use the # symbol:

# This is a big heading (Level 1)
## This is a smaller heading (Level 2)
### This is an even smaller heading (Level 3)

The more # symbols you add, the smaller the heading becomes. It's like organizing your thoughts from most important to least important!

space after #

Do not forget to add a space after #. Although the syntax of markdown is simple, some syntax is still required.

1.2.2 Lists

Lists help organize information in a clear way. There are two types numbered and bullet lists.

Numbered Lists 

1. First item
2. Second item
3. Third item

This creates

  1. First item
  2. Second item
  3. Third item

Perfect for step-by-step instructions or ranking things.

Bullet Lists

- This is one point
- This is another point
- And one more point

This creates

  • This is one point
  • This is another point
  • And one more point

Great for when the order doesn't matter!

1.2.3 Code

If you're learning to code or want to show someone a specific command, you can format it as code

For a single line of code, use backticks (` `) around the text: 

`print("Hello World!")`

This displays as: print("Hello World!")

For multiple lines of code, use three backticks at the beginning and end:

    ```dart
    void main() {
    print("Hello, World!");
    }
    ```

Backticks must start the line

The backticks should appear at the beginning of the line.

Want to share a cool website? You can create links like this:

[Flutter](https://flutter.dev/)

This creates: Flutter

The text in square brackets is what people will see, and the URL in parentheses is where the link goes.

1.2.5 Images

Adding images in Markdown is very similar to adding links, but with an exclamation mark at the beginning:

![Image description](https://example.com/image.jpg)

The text in square brackets is the image description or alt text (what appears if the image doesn't load), and the URL in parentheses is the path to the image.

If you're adding an image from your computer (like in Obsidian), you would use a relative path instead:

![My cat](images/my-cat.jpg)

1.2.6 Bold, Italic, lines

You can also

  • Make text bold with two asterisks: **bold text**

  • Make text italic with one asterisk: *italic text*

  • Create a horizontal line to separate sections with three dashes: 

    ---