Skip to content

Getting Started with Markdown

What is Markdown?

Markdown is a lightweight markup language that lets you format plain text using simple syntax. Files using Markdown have the .md extension and can be easily converted to HTML or other formats. Its human-readable format makes it perfect for documentation that needs to be both machine-processable and author-friendly.

Why Markdown for Docs-as-Code?

When practicing docs-as-code, Markdown shines because:

  • Collaboration Ready: Easy to read/write for both technical and non-technical contributors
  • Toolchain Integration: Supported by all major platforms (GitHub, GitLab, etc.) and static site generators
  • Low Barrier: Quick to learn compared to complex formatting tools

Essential Markdown Syntax

Here are fundamental formatting patterns:

# Header 1
## Header 2
### Header 3

**Bold Text** or __Bold__
*Italic Text* or _Italic_

- Unordered List
- With hyphens

1. Ordered List
2. With numbers

[Link Text](https://example.com)

![Alt Text](image.jpg)

`Inline Code`

Learn More

Master Markdown through these resources:
πŸ”— The Markdown Guide - Interactive tutorials and cheat sheet
πŸ”— CommonMark Spec - Official syntax standardization