The Definitive Guide to Markdown for Beginners and Developers.
Markdown is a lightweight markup language created to allow writing formatted text using only plain text. Unlike HTML, Markdown prioritizes simplicity, readability, and writing speed, without sacrificing structure.
A Markdown file can be easily read even without rendering, and can still be automatically converted to HTML, PDF, or other formats.
Markdown was created in 2004 by John Gruber, with important contributions from Aaron Swartz. At the time, creating content for the web required technical knowledge of HTML, which made the process slow and not very accessible for writers, beginner developers, and content creators.
John Gruber, a writer and developer best known for the Daring Fireball website, aimed to create a markup language that was simple, readable, and easy to write, while still being convertible to HTML. His experience with usability and technical writing directly influenced the core principles of Markdown.
Aaron Swartz, a programmer and internet activist, collaborated on the early development of the language. Even at a young age, Aaron had already contributed to fundamental projects of the modern web, such as RSS 1.0, Creative Commons, and the founding of Reddit. His vision defended that technology should be open, simple, and accessible to everyone — values that became deeply embedded in Markdown. In 2011, years after his contribution to Markdown and other key web projects, Aaron Swartz faced a judicial process in the United States after carrying out mass downloads of academic articles with the goal of expanding access to knowledge. The legal pressure and severity of the case led to his death in 2013, at the age of 26. His case became a global landmark in the debate over access to information, digital freedom, and the limits of the legal system in the internet era.
Writing content for the web required technical knowledge of HTML, making the process slow and not very accessible.
Markdown emerged with the proposal to:
Be easy to write.
Be easy to read.
Focus on content, not markup.
Automatically convert to HTML.
With the growth of documentation culture and, especially, with the adoption of Markdown by GitHub, it became the standard for READMEs and technical documentation.
|
|
| John Gruber | Aaron Swartz 🕊️ |
Official adoption by GitHub.
The rise of open source.
Documentation culture in projects.
An extremely low learning curve.
Fast writing without relying on visual editors.
Markdown is widely used in:
📄 Repository README.md files.
👤 GitHub Profile READMEs.
📚 Technical documentation.
📝 Wikis.
🧠 Notion, Obsidian, Joplin.
💬 Discord, Slack, Reddit.
⚙️ DevOps and CI/CD.
✍️ Blogs and static site generators.
📘 What is a README.md and why is it important?.
The README.md file is the first contact someone has with your project. It works as the repository’s business card.
What is this project?.
What is it for?.
How do you use or run it?.
Which technologies were used?.
How can someone contribute?.
Have fewer stars.
Have fewer forks.
Be less used.
The topics below are optional, but highly recommended:
Introduction.
Clear and objective project description.
Makes navigation easier in long READMEs.
Features.
List of what the project does.
Technologies used.
Languages, frameworks, and tools.
How to run.
Step-by-step instructions to run the project.
Contributing.
Rules for forks and pull requests.
License.
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
Use headings hierarchically and do not skip levels.
Bold
**bold**
__bold__
Italic
*italic*
_italic_
Bold and Italic
***emphasis***
TStrikethroughT
~~strikethrough~~
🔹 Paragraphs and line breaks
A blank line creates a new paragraph.
For a forced line break:
Line 1. Line 2.
🔹 Horizontal rules
use (---).
use (***).
__
use (__).
🔹 Blockquotes This is a quote
Nested:
> Main quote
>> Secondary quote
🔹 Lists
1.Ordered lists
1. Item one
2. Item two
3. Item three
- Unordered lists
- Item
* Item
+ Item
- Nested lists
- Main item
- Subitem
- Task lists
- [ ] Pending task
- [x] Completed task
🔹 Code
Inline.code("Hello")
`console.log("Hello")`
Code block
Code here
Block with language
print("Hello, Markdown!")###🔹 Links md GitHub
Direct link:
Local file links:
🔹 Images
Image with link:
🔹 Tables
Column A | Column B
-------- | --------
Item 1 | Item 2
:--- | :---: | ---:Alignment::--- | :---: | ---:
:--- | :---: | ---:
🔹 Embedded HTML in Markdown
<details>
<summary>See more</summary>
Hidden content
</details>
Useful for more interactive READMEs.
🔹 Emojis
:rocket: :fire: :computer:
🚀 🔥 💻 To see a full list of emojis and their syntax, click here:EMOJIS Use sparingly.
GitHub uses a variation called GFM, which adds:
Tables.
Task lists.
Syntax highlighting.
Strikethrough.
Not all Markdown works the same way outside GitHub.
Not suitable for complex layouts
Limited visual styling.
Differences between parsers.
For advanced cases, use Markdown + HTML.
Use hierarchical headings.
Avoid huge READMEs without a table of contents.
Use code blocks correctly.
Be clear and objective.
Prioritize readability.
This project is licensed under the Creative Commons Attribution 4.0 (CC BY 4.0) license.
You may use, adapt, and redistribute this content, including for commercial purposes, as long as proper credit is given to the original author.
Copyright (c) 2026 Jeferson Rodrigo