Greetings, brave adventurer! Welcome to Markdown Mastery — the quest that teaches you the universal language of technical documentation. Markdown is used everywhere: README files, blog posts, wikis, chat messages, and even this very quest you’re reading. Once you master it, you’ll be able to create beautifully formatted content with nothing but plain text.

🎯 Quest Objectives

Primary Objectives (Required for Quest Completion)

• Master Text Formatting — Use headings, bold, italic, and lists
• Create Links and Images — Add hyperlinks and embed images
• Write Code Blocks — Format inline code and fenced code blocks with syntax highlighting
• Build Tables — Structure data in Markdown tables

Secondary Objectives (Bonus Achievements)

• Use Blockquotes and Callouts — Highlight important information
• Create Task Lists — Add interactive checkboxes
• Master Extended Syntax — Footnotes, abbreviations, definition lists
• Write a Complete README — Create a project README from scratch

Mastery Indicators

• Can write a well-structured document using only Markdown
• Can format code examples with proper language highlighting
• Can create tables and organize information visually
• Can write a professional README for any project

🗺️ Quest Prerequisites

📋 Knowledge Requirements

• Basic text editing skills (typing, copying, saving files)

🛠️ System Requirements

• Text editor with Markdown preview (VS Code with built-in preview recommended)
• Alternatively: any text editor + a browser for previewing

💡 VS Code Markdown Preview

Open any .md file and press Cmd+Shift+V (macOS) or Ctrl+Shift+V (Windows/Linux) to see the rendered preview side-by-side.

🧙‍♂️ Chapter 1: Text Formatting — The Building Blocks

Every great document starts with well-organized text. Headings, emphasis, and lists form the skeleton of all Markdown content.

📝 Headings

# Heading 1 (Page Title)
## Heading 2 (Major Section)
### Heading 3 (Subsection)
#### Heading 4 (Detail)
##### Heading 5 (Minor Detail)
###### Heading 6 (Smallest)

Rule of thumb: Use headings in order — never skip levels (e.g., don’t jump from # to ###).

✨ Text Emphasis

**bold text**
*italic text*
***bold and italic***
~~strikethrough~~
`inline code`

Renders as:

• bold text
• italic text
• bold and italic
• strikethrough
• inline code

📋 Lists

Unordered (bullet) lists:

- Item one
- Item two
  - Nested item
  - Another nested item
- Item three

Ordered (numbered) lists:

1. First step
2. Second step
3. Third step
   1. Sub-step a
   2. Sub-step b

Task lists (checkboxes):

- [ ] Incomplete task
- [x] Completed task
- [ ] Another task

⚡ Quick Wins

• Create a file called practice.md
• Add a heading hierarchy (H1 through H3)
• Write a paragraph with bold and italic text
• Create an unordered list with nested items
• Add a task list with at least 3 items

🧙‍♂️ Chapter 2: Links, Images, and Code — Connecting Content

Now you’ll learn to link to external resources, embed images, and format code — the elements that make documentation truly useful.

🔗 Links

<!-- Inline link -->
[GitHub](https://github.com)

<!-- Link with title (shows on hover) -->
[GitHub](https://github.com "Visit GitHub")

<!-- Reference-style link -->
[GitHub][gh-link]

[gh-link]: https://github.com

<!-- Auto-linked URL -->
<https://github.com>

🖼️ Images

<!-- Inline image -->
![Alt text describing the image](path/to/image.png)

<!-- Image with title -->
![Logo](images/logo.png "Company Logo")

<!-- External image -->
![Octocat](https://github.githubassets.com/images/modules/logos_page/Octocat.png)

💻 Code Blocks

Inline code — wrap with single backticks:

Use the `git commit` command to save changes.

Fenced code blocks — wrap with triple backticks and specify the language:

```python
def hello():
    print("Hello, World!")
```text

```bash
echo "Hello from the terminal"
```text

```javascript
console.log("Hello, JavaScript!");
```text

The language identifier enables syntax highlighting — always include it!

💬 Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> > Nested blockquotes work too.

This is a blockquote. It can span multiple lines.

⚡ Quick Wins

• Add a link to your favorite website
• Insert an image (use any URL or local path)
• Write a Python code block with syntax highlighting
• Create a blockquote with a meaningful quote

🧙‍♂️ Chapter 3: Tables, Separators, and Advanced Formatting

With the basics mastered, you’re ready for the advanced formatting that makes documentation professional and scannable.

📊 Tables

| Feature    | Markdown     | HTML         |
|------------|--------------|--------------|
| Bold       | `**text**`   | `<b>text</b>`|
| Italic     | `*text*`     | `<i>text</i>`|
| Code       | `` `code` `` | `<code>`     |

Renders as:

Column alignment:

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| Left         |    Center      |         Right |

➖ Horizontal Rules

---
***
___

All three produce a horizontal line — use --- for consistency.

📝 Escaping Special Characters

To show Markdown symbols literally, use a backslash:

\*not italic\*
\# not a heading
\[not a link\]

🔢 Footnotes (Extended Syntax)

Here is a statement that needs a source[^1].

[^1]: This is the footnote with the reference.

🖼️ HTML in Markdown

When Markdown isn’t enough, you can use raw HTML:

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

Hidden content goes here. Supports **Markdown** inside!

</details>

⚡ Quick Wins

• Create a table with at least 3 columns and 3 rows
• Add a horizontal rule between two sections
• Use a collapsible <details> section
• Escape a Markdown character to display it literally

🧙‍♂️ Chapter 4: Frontmatter — Metadata at the Top of the Scroll

When your Markdown lives inside a real site — a blog, a wiki, a docs platform like Jekyll, Hugo, or this very IT-Journey codex — a hidden block of metadata at the very top tells the engine how to render, title, and categorize the page. That block is called frontmatter, and it’s the bridge between plain Markdown and a published page.

📜 The Frontmatter Block

Frontmatter is YAML enclosed between two --- fences, and it must be the very first thing in the file:

---
title: "Deploying Jekyll to Azure Cloud"
description: "Step-by-step guide to deploying a Jekyll site on Azure Static Web Apps."
date: 2026-03-31
author: bamr87
categories:
  - devops
tags:
  - jekyll
  - azure
draft: false
---

Everything below the closing --- is your normal Markdown body. The engine reads the metadata, then renders the rest.

🔑 Common Fields

Rule of thumb: categories and tags are YAML lists — each item on its own line prefixed with -. At minimum, always include title and description.

🛠️ Frontmatter Best Practices

• Always set a clear title and description — they drive SEO and link previews
• Use draft: true while a page is a work in progress to keep it out of production
• Keep categories and tags consistent across pages so filtering works
• Bump lastmod when you revise a page so readers and search engines see freshness

⚡ Quick Wins

• Add a frontmatter block to your practice.md with title and description
• Include a tags YAML list with at least two tags
• Set draft: true, preview, then flip it to false

🎮 Mastery Challenges

🟢 Novice Challenge: Personal Profile Page

• Create a profile.md with your name as H1
• Add a short bio paragraph with bold and italic text
• Include a list of your skills
• Add links to your social profiles or projects

🟡 Intermediate Challenge: Project README

• Create a complete README.md for a real or imaginary project
• Include: project title, description, installation steps, usage examples
• Add a table of features or commands
• Include at least one code block with the correct language spec
• Add a “Contributing” section with a task list

🔴 Advanced Challenge: Technical Tutorial

• Write a 500+ word tutorial in Markdown on any technical topic
• Use all elements learned: headings, lists, code blocks, tables, links, images
• Include a table of contents with anchor links
• Use blockquotes for tips and warnings
• Add footnotes for references

🏆 Quest Completion Validation

Portfolio Artifacts Created

• Practice File — practice.md with all basic formatting
• Project README — Complete README.md for a project
• Code Examples — Properly formatted code blocks with language highlighting

Skills Demonstrated

• Text Formatting — Headings, bold, italic, lists
• Rich Content — Links, images, blockquotes
• Code Documentation — Inline code and fenced blocks
• Data Presentation — Tables with alignment

📚 References & Resources

• Markdown Guide — Syntax Reference with Basic and Extended Cheat Sheets
• GitHub Flavored Markdown Spec
• CommonMark Specification
• Dillinger — Online Markdown Editor
• Markdown Tutorial — Interactive Practice
• VS Code Markdown Features

🕸️ Knowledge Graph

Structured wiki-links connect this quest to the IT-Journey knowledge graph. Open the Obsidian Graph View to explore connections.

Level hub: [[Level 0000 - Foundation & Init World]] Overworld: [[🏰 Overworld - Master Quest Map]] Recommended: [[Terminal Fundamentals: Command Line Navigation Quest]] Obsidian docs: [[Obsidian Knowledge Graph and Wiki Links]]