Complete Markdown Guide with HTML Comparisons

---

Part One: Basics and Core Elements in Markdown

Markdown is a lightweight markup language that allows you to format your writing using plain text. These texts are easily converted to HTML for display on websites.

In this guide, you'll learn all Markdown tools and elements with live examples and their HTML equivalents.

---

Headings

To create headings in Markdown, use the hash symbol (#). The number of hashes determines the heading level (from 1 to 6).

Structure and Comparison:

Heading Level	Markdown Code	HTML Code
Main Heading (Largest)	# Heading Level 1	<h1>Heading Level 1</h1>
Subheading	## Heading Level 2	<h2>Heading Level 2</h2>
Sub-subheading	### Heading Level 3	<h3>Heading Level 3</h3>
Small Heading	#### Heading Level 4	<h4>Heading Level 4</h4>

Note: Always add a space after the # symbol; otherwise, some renderers won't recognize it as a heading.

---

Text Formatting

For emphasis, bold text, or strikethrough, use asterisks (*) or underscores (_).

Structure and Comparison:

Formatting Type	Markdown Code	HTML Code	Rendered Output
Bold	**This text is bold**	<strong>This text is bold</strong>	This text is bold
Italic	*This text is italic*	<em>This text is italic</em>	This text is italic
Bold & Italic	***This text is both***	<strong><em>This text is both</em></strong>	This text is both
Strikethrough	~~This text is expired~~	<del>This text is expired</del>	~~This text is expired~~

---

Lists

Lists are divided into ordered (numbered) and unordered (bulleted) types.

Unordered Lists

Use -, *, or + symbols.

Markdown Code:

- First item
- Second item
  - Sub-item one (indent with two or four spaces)
  - Sub-item two

HTML Equivalent:

<ul>
  <li>First item</li>
  <li>Second item
    <ul>
      <li>Sub-item one</li>
      <li>Sub-item two</li>
    </ul>
  </li>
</ul>

Ordered Lists

Use numbers followed by a dot (.).

Markdown Code:

1. Step one
2. Step two
3. Step three

HTML Equivalent:

<ol>
  <li>Step one</li>
  <li>Step two</li>
  <li>Step three</li>
</ol>

---

Links & Images

The structure for links and images is very similar, except images have an exclamation mark (!) at the beginning.

Links

Formula: [Link Text](URL)

• Markdown: [My Website](https://example.com)
• HTML: <a href="https://example.com">My Website</a>

Images

Formula: ![Alt Text](Image URL)

• Markdown: ![Site Logo](https://example.com/logo.png)
• HTML: <img src="https://example.com/logo.png" alt="Site Logo" />

---

Blockquotes

To quote text from a book, website, or person, use the greater-than sign (>).

Markdown Code:

> "Success in programming comes from repeating small mistakes and solving them."

HTML Equivalent:

<blockquote>
  <p>"Success in programming comes from repeating small mistakes and solving them."</p>
</blockquote>

---

Code Blocks

One of the most attractive features of Markdown for developers is code display.

Inline Code

For code words within regular text (like variable names or commands), wrap them in backticks (`).

• Markdown: Use the command `npm install `.
• HTML: Use the command <code>npm install</code>.

Fenced Code Blocks

For multiple lines of code, wrap them with three backticks (`````). You can also specify the programming language for syntax highlighting.

Markdown Code:

```javascript
function greet(name) {
    console.log("Hello, " + name);
}
greet("Saleh");
```

HTML Equivalent:

<pre>
  <code class="language-javascript">
function greet(name) {
    console.log("Hello, " + name);
}
greet("Saleh");
  </code>
</pre>

---

Tables

Use vertical bars (|) for columns and hyphens (-) to separate headers from the body. Use : to align text (left, center, or right).

Markdown Code:

| Project Name | Programming Language | Development Status |
| :--- | :---: | ---: |
| Educational Blog | PHP (Laravel) | In Progress (Right) |
| Drawing Game | Node.js | Completed (Center) |
| Linux Simulator | Java | Completed (Left) |

HTML Equivalent:

<table>
  <thead>
    <tr>
      <th style="text-align: right;">Project Name</th>
      <th style="text-align: center;">Programming Language</th>
      <th style="text-align: left;">Development Status</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: right;">Educational Blog</td>
      <td style="text-align: center;">PHP (Laravel)</td>
      <td style="text-align: left;">In Progress</td>
    </tr>
  </tbody>
</table>

---

Task Lists

For daily tasks or project checklists, combine unordered lists with brackets. An x inside brackets means the item is completed.

Markdown Code:

- [x] Frontend design for blog
- [ ] Write educational Markdown content
- [ ] SEO optimization

HTML Equivalent:

<ul>
  <li><input type="checkbox" checked disabled> Frontend design for blog</li>
  <li><input type="checkbox" disabled> Write educational Markdown content</li>
  <li><input type="checkbox" disabled> SEO optimization</li>
</ul>

---

Horizontal Rule

To create a horizontal line and separate different sections, use three hyphens (---) or three asterisks (***) on a separate line.

• Markdown: ---
• HTML: <hr />

---

Part Two: Advanced Techniques and Special Tricks

Escaping Characters

Sometimes you want to display Markdown symbols (like * or #) as plain text. Use a backslash (\) before the character.

Markdown Code: \*This text is no longer italic\* HTML Equivalent: *This text is no longer italic* Rendered Output: This text is no longer italic (displayed with asterisks)

---

Anchor Links

For long articles, create a table of contents that navigates to specific sections on the same page.

Markdown Code: [Go to Tables section](#tables) HTML Equivalent: <a href="#tables">Go to Tables section</a>

---

Mathematical Formulas (LaTeX)

Many modern blogging platforms support LaTeX math formulas using dollar signs ($).

Inline Formula:

Einstein's famous formula is $E = mc^2$.

Display Formula:

$$
f(x) = \int_{-\infty}^{\infty} e^{-x^2} dx
$$

HTML Equivalent: HTML doesn't have direct tags; it uses JavaScript libraries like MathJax or MathML:

<math xmlns="http://www.w3.org/1998/Math/MathML">
  <mi>E</mi><mo>=</mo><mi>m</mi><msup><mi>c</mi><mn>2</mn></msup>
</math>

---

Footnotes

Reference a word with an explanatory note at the end of the page using [^1].

Markdown Code:

Markdown was created in 2004 by John Gruber [^1].

[^1]: John Gruber is an American writer and programmer.

HTML Equivalent:

Markdown was created in 2004 by John Gruber <a href="#fn1" id="ref1">[1]</a>.

<!-- At the end of the page -->
<hr>
<ol>
  <li id="fn1">John Gruber is an American writer and programmer. <a href="#ref1">↩</a></li>
</ol>

---

Raw HTML in Markdown

One of Markdown's biggest advantages is that if you don't know an element or it doesn't exist in Markdown, you can write HTML directly! Markdown renderers execute HTML without modification.

Examples:

• Changing text color:

  • <span style="color:blue;">This text is blue</span>

• Centering text:

  • <p align="center">This text is centered</p>

• Creating a button that opens in a new tab:

  • <a href="https://example.com" target="_blank">Download File</a>

---

Collapsible Details

Create interactive sections that users can expand or collapse.

Mixed Markdown and HTML Code:

<details>
<summary>Click to see the answer</summary>

Here you can hide long texts or even other Markdown code to keep the page uncluttered.
</details>

---

Part Three: Choosing the Best Markdown Editors by Operating System

Writing Markdown in a plain text editor (like Notepad) is possible, but specialized editors with Live Preview or modern WYSIWYG systems make the experience much better.

---

Desktop (Windows / macOS / Linux)

Typora (Best for Writers and Content Creators)

• Why it's great: Typora revolutionized Markdown editors. It eliminated the two-pane system (code on the left, preview on the right). When you type **hello**, the word "hello" becomes bold immediately, and the asterisks disappear.
• Rendering and Export: Live rendering. Exports to HTML, PDF, and Word with exceptional cleanliness.
• Platform: Windows, macOS, Linux (Paid with free trial)

VS Code (Best for Developers and Programmers)

• Why it's great: If you're already a developer with VS Code installed, you don't need any other tool. With powerful extensions, it becomes a Markdown powerhouse.
• Rendering and Export: Press Ctrl + Shift + V (or Cmd + Shift + V on Mac) for a side-by-side live preview. With the Markdown PDF extension, you can create beautiful exports.
• Platform: Windows, macOS, Linux (Completely free and open source)

Obsidian (Best for Note-Taking and Connecting Ideas)

• Why it's great: If your goal is to build a personal knowledge base or connect your blog articles, Obsidian is unmatched. Files are stored locally in .md format on your hard drive.
• Rendering and Export: Has both Live Preview (similar to Typora) and Source mode (showing raw code).
• Platform: Windows, macOS, Linux (Free for personal use)

---

macOS (Exclusive Options)

• Ulysses: The king of text editors in the Apple ecosystem. A minimalist environment for long-form writing with full Markdown support and direct WordPress publishing.
• iA Writer: An editor focused solely on "just writing." Beautiful proprietary fonts and subtle color-coding for Markdown structure.

---

Android

• PocketMark: A modern, minimalist, and fast Markdown editor for Android with full support for LaTeX math and tables.
• Markor: A completely free and open-source app with no ads. Allows you to open .md files, view live rendering in split-screen mode, and export to PDF.

---

iOS (iPhone and iPad)

• Ulysses (iOS version): Fully syncs with the Mac version and is the best environment for blogging on iPad or iPhone.
• Taio: A specialized Markdown editor for iOS with excellent live rendering, powerful clipboard tools, and custom macros for formatting.

---

Summary

Operating System	First Choice (Speed & Simplicity)	Second Choice (Professional/Development)	Rendering Status
Windows	Typora	VS Code	Live / Side-by-side preview
macOS	iA Writer or Typora	Obsidian	Live / Native
Linux	Typora	VS Code	Live / Extensions
Android	PocketMark	Markor	Toggle between editor and preview
iOS	Ulysses	Taio	Live with PDF/HTML export