Markdown Guide

Hello! For some time now, I’ve been following the Full Stack JavaScript course from The Odin Project. As part of the Node.js module, one of the projects involves building a personal blog. I decided to include it on my personal website to give it more practical value and avoid it becoming just another course project.

In a future post, I may share more about how I developed the project. For this article, what matters is that I decided to create a Markdown guide that I could use as a reference when writing blog posts.

To render Markdown in this application, I used:

react-markdown
react-syntax-highlighter
remark
remark-gfm
remark-github-alerts
rehype-raw
rehype-slug
mermaid

Below, you will find a guide/reference on how to write Markdown. In each section, the Markdown code will appear first, followed by the resulting output it produces.

Headings
Paragraphs & Line Breaks
Text Formatting
Lists
Links
Images
Blockquotes
Inline Code
Code Blocks
Horizontal Rules
Tables
Task Lists
HTML in Markdown
Emojis
Keyboard Keys
Collapsible Sections
Callouts / Alerts
Footnotes
Mermaid Diagrams

Headings

# H1
## H2
### H3
#### H4
##### H5
###### H6

H1

H2

H3

H4

H5

H6

Blog Structure Example

# Blog Title

## Main Section

### Subsection

#### Smaller Topic

Blog Title

Main Section

Subsection

Smaller Topic

Alternative H1 / H2 Syntax

Heading 1
=========

Heading 2
---------

Heading 1

Heading 2

Paragraphs & Line Breaks

This is the first paragraph.

This is the second paragraph.

This is the first paragraph.

This is the second paragraph.

Forced Line Break

(Add spaces to the end of the line)
Line one.
Line two.

Line one.
Line two.

Text Formatting

**Bold**
*Italic*
***Bold Italic***
~~Strikethrough~~
`Inline code`

Bold
Italic
Bold Italic
~~Strikethrough~~
Inline code

Alternative Syntax

__Bold__
_Italic_

Bold
Italic

Combining Formatting

**This text is _very important_**

This text is very important

Highlight Important Notes

**Important:** Always optimize images.

Important: Always optimize images.

Lists

Unordered Lists

- Item one
- Item two
- Item three

Item one
Item two
Item three

Alternative Syntax

* Item one
* Item two

Item one
Item two

Ordered Lists

1. First step
2. Second step
3. Third step

First step
Second step
Third step

Nested Lists

- Frontend
  - React
  - Vue

- Backend
  - Node.js
  - Django

Frontend
- React
- Vue
Backend
- Node.js
- Django

Deep Nesting

- Web Development
  - Frontend
    - React
    - Vue
  - Backend
    - Node.js

Web Development
- Frontend
  - React
  - Vue
- Backend
  - Node.js

Mixed Lists

1. Install dependencies
2. Setup project

   - Configure routes
   - Add components

3. Deploy

Install dependencies
Setup project
- Configure routes
- Add components
Deploy

Links

Basic Link

[Google](https://google.com)

Google

Link With Title

[Visit Google](https://google.com "Google Website")

Visit Google

Automatic URL

<https://google.com>

https://google.com

Email Link

<email@example.com>

email@example.com

Internal Anchor Links

[Go to Installation](#installation)

Go to Installation

Relative Links

[About](./about.md)

About

Images

Basic Image

![Alt text](image.png)

Alt text

Image With Title

![Portfolio](portfolio.png "Portfolio Screenshot")

Portfolio

Clickable Image

[![Preview](image.png)](https://example.com)

Remote Images

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

Hero

Image Best Practices

Bad:

![image](hero.png)

Good:

![Developer writing React code](hero.png)

Width Styling (HTML)

<img src="image.png" width="500" />

Blockquotes

Simple Quote

> This is a quote.

This is a quote.

Multi-line Quote

> This is line one.
>
> This is line two.

This is line one.

This is line two.

Nested Quote

> Main quote
>> Nested quote

Main quote

Nested quote

Quote With Formatting

> **Important:** Read the documentation.

Important: Read the documentation.

Inline Code

Use `npm install`

Use npm install

Use `useEffect()` carefully.

Use useEffect() carefully.

Install packages with `pnpm install`

Install packages with pnpm install

Code Blocks

Generic Code Block

```
Hello World
```

JavaScript

```js
function hello() {
  console.log("Hello");
}
```

function hello() {
  console.log("Hello");
}

TypeScript

```ts
type User = {
  name: string;
};
```

type User = {
  name: string;
};

React JSX

```jsx
export default function App() {
  return <h1>Hello</h1>;
}
```

export default function App() {
  return <h1>Hello</h1>;
}

TSX

```tsx
type Props = {
  title: string;
};

export default function Card({ title }: Props) {
  return <h1>{title}</h1>;
}
```

type Props = {
  title: string;
};

export default function Card({ title }: Props) {
  return <h1>{title}</h1>;
}

HTML

```html
<h1>Hello</h1>
```

<h1>Hello</h1>

CSS

```css
.container {
  display: flex;
}
```

.container {
  display: flex;
}

Bash Terminal

```bash
npm install
npm run dev
```

npm install
npm run dev

JSON

```json
{
  "name": "blog"
}
```

{
  "name": "blog"
}

Diff Syntax

```diff
+ Added feature
- Removed bug
```

+ Added feature
- Removed bug

Horizontal Rules

---

Escaping Characters

\# Not a heading 
\* Not italic
\` Not code

# Not a heading

* Not italic

` Not code

Tables

| Name | Role |
|------|------|
| Pablo | Developer |
| Anna | Designer |

Name	Role
Pablo	Developer
Anna	Designer

Table Alignment

| Left | Center | Right |
|:-----|:------:|------:|
| Text | Text | Text |

Left	Center	Right
Text	Text	Text

Pricing Table Example

| Plan | Price |
|------|------:|
| Basic | $10 |
| Pro | $25 |
| Premium | $50 |

Plan	Price
Basic	$10
Pro	$25
Premium	$50

Task Lists

- [x] Finished task
- [ ] Pending task

Finished task
Pending task

Tutorial Example

- [x] Install React
- [x] Setup routing
- [ ] Add authentication

Install React
Setup routing
Add authentication

HTML in Markdown

Basic HTML

<div>
  Hello World
</div>

Hello World

Styled HTML

<p style="color:red;">
  Red text
</p>

Red text

Image With Custom Width

<img src="image.png" width="400" />

Centered Content

<div align="center">
  Centered text
</div>

Centered text

YouTube Embed (HTML)

<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/VIDEO_ID"
  frameborder="0"
  allowfullscreen
></iframe>

Useful for blogs with videos.

Emojis

Emoji Shortcodes

:rocket:
:fire:
:white_check_mark:
:warning:
:star:

🚀
🔥
✅
⚠️
⭐

Direct Emojis

🚀 🔥 ✅ ⚠️ ⭐

🚀 🔥 ✅ ⚠️ ⭐

Common Blog Emojis

💡 Tip
⚠️ Warning
🔥 Trending
🚀 Launch
📌 Important

💡 Tip
⚠️ Warning
🔥 Trending
🚀 Launch
📌 Important

Keyboard Keys

Press <kbd>Ctrl</kbd> + <kbd>C</kbd>

Press Ctrl + C

Press <kbd>Cmd</kbd> + <kbd>S</kbd>

Press Cmd + S

Useful for tutorials.

Collapsible Sections

Basic Collapsible

<details>
  <summary>Click to expand</summary>

Hidden content here.

</details>

Click to expand

Hidden content here.

FAQ Example

<details>
  <summary>What is React?</summary>

React is a JavaScript library for UI.

</details>

What is React?

React is a JavaScript library for UI.

Useful for:

FAQs
Long explanations
Optional content
Advanced sections

Callouts / Alerts

Note

> [!NOTE]
> Useful information.

Note

Useful information.

Tip

> [!TIP]
> Helpful advice.

Tip

Helpful advice.

Important

> [!IMPORTANT]
> Read carefully.

Important

Read carefully.

Warning

> [!WARNING]
> Be careful.

Warning

Be careful.

Danger

> [!CAUTION]
> This action cannot be undone.

Caution

This action cannot be undone.

Footnotes

React is a UI library.[^1]

[^1]: Created by Facebook.

React is a UI library.¹

Useful for:

Sources
References
Citations

Mermaid Diagrams

Requires Mermaid support in your markdown renderer.

Flowchart

```mermaid
graph TD
    A[Start] --> B[Build Blog]
    B --> C[Deploy]
```

Sequence Diagram

```mermaid
sequenceDiagram
    User->>Server: Request
    Server->>Database: Fetch data
    Database-->>Server: Return data
    Server-->>User: Response
```

Blog Architecture Example

```mermaid
graph LR
    Markdown --> ReactMarkdown
    ReactMarkdown --> BlogPage
```

Advanced Code Blocks

Line Numbers

```js showLineNumbers
function hello() {
  console.log("Hello")
}
```

1function hello() {
2  console.log("Hello")
3}

Created by Facebook. ↩

Markdown Guide

Table of Contents

Headings

H1

H2

H3

H4

H5

H6

Blog Structure Example

Blog Title

Main Section

Subsection

Smaller Topic

Alternative H1 / H2 Syntax

Heading 1

Paragraphs & Line Breaks

Forced Line Break

Text Formatting

Alternative Syntax

Combining Formatting

Highlight Important Notes

Lists

Unordered Lists

Alternative Syntax

Ordered Lists

Nested Lists

Deep Nesting

Mixed Lists

Links

Basic Link

Link With Title

Automatic URL

Email Link

Internal Anchor Links

Relative Links

Images

Basic Image

Image With Title

Clickable Image

Remote Images

Image Best Practices

Width Styling (HTML)

Blockquotes

Simple Quote

Multi-line Quote

Nested Quote

Quote With Formatting

Inline Code

Code Blocks

Generic Code Block

JavaScript

TypeScript

React JSX

TSX

HTML

CSS

Bash Terminal

JSON

Diff Syntax

Horizontal Rules

Escaping Characters

Tables

Table Alignment

Pricing Table Example

Task Lists

Tutorial Example

HTML in Markdown

Basic HTML

Styled HTML

Image With Custom Width

Centered Content

YouTube Embed (HTML)

Emojis

Emoji Shortcodes

Direct Emojis

Common Blog Emojis

Keyboard Keys

Collapsible Sections

Basic Collapsible