Lingua-e
Markdown tutorial

Markdown Documentation That Gets You Noticed as a Developer

A complete reference guide to Markdown syntax, with best practices for READMEs, pull request descriptions, and technical documentation.

Every developer writes documentation. README files, pull request descriptions, Jira tickets, internal wikis, Notion pages: they all use Markdown. But most developers learn just enough syntax to get by and never discover the features that make their documentation stand out.

This guide covers everything from the basics to the professional patterns that make documentation easy to read, easy to maintain, and easy to find.

In this guide
  1. Why Markdown matters
  2. Basic syntax
  3. Links and images
  4. Lists
  5. Code
  6. Tables
  7. Blockquotes
  8. GitHub Flavored Markdown
  9. README best practices
  10. Quick reference

Why Markdown matters for developers

Markdown is the universal language of developer documentation. GitHub, GitLab, Bitbucket, Notion, Linear, Confluence, Jira, and Slack all render Markdown. When you write clear, well-structured documentation, your teammates can understand your work without asking you to explain it. That visibility compounds over time: a developer who writes good documentation gets noticed in ways that a developer who only writes good code does not.

Markdown has two key advantages over other formats. First, it is plain text, so it works in any editor, travels through version control without binary conflicts, and renders in any Markdown viewer. Second, the syntax is minimal enough to read without rendering: a file full of # and ** is still legible.

Basic syntax

Headers

Headers create the structure and hierarchy of a document. They work exactly like the headings you see on any webpage: the browser (or Markdown renderer) makes them larger and bolder than body text, and each level is smaller than the one above it.

The number of # symbols sets the level: one # gives you the largest heading (H1), six ###### gives you the smallest (H6). Each extra # drops you one level down in the hierarchy.

In practice, most README files only use H1 through H3. H1 is the project name — there should only ever be one per document. H2 breaks the document into major sections like Installation, Usage, and Contributing. H3 breaks those sections into subsections. H4 through H6 exist but are rarely needed; if you find yourself using H5, the document probably needs restructuring rather than more nesting.

Syntax
# H1 — Project title
## H2 — Main section
### H3 — Subsection
#### H4 — Sub-subsection
##### H5 — Minor heading
###### H6 — Smallest heading
Rendered

H1 — Project title

H2 — Main section

H3 — Subsection

H4 — Sub-subsection

H5 — Minor heading
H6 — Smallest heading

Text formatting

Bold and italic are the two formatting tools you will use most. Strikethrough is useful in task lists and changelogs.

FormatSyntaxResult
Bold**bold**bold
Italic*italic*italic
Bold + italic***bold and italic***bold and italic
Strikethrough~~strikethrough~~strikethrough

Paragraphs and line breaks

Separate paragraphs with a blank line. A single newline inside a paragraph is ignored. To force a line break within a paragraph, end the line with two spaces or a backslash (\).

Links

The link syntax is [text](url). The text in brackets is what the reader sees and clicks — it can be anything, completely independent from the URL. You can also add a tooltip that appears on hover by putting a title in quotes after the URL: [text](url "Tooltip text").

Syntax
Visit [Lingua-e](https://www.lingua-e.com) to practice.
Rendered

Visit Lingua-e to practice.

Images

Images use the same syntax as links but with a leading !. The text in brackets is the alt text, which is displayed when the image cannot be loaded and is read by screen readers.

Syntax
![Keystroke progression graph](https://github.com/roxana-lafuente/ResearchAnalyzer/raw/master/images/keystroke_progression_graph.png)
Rendered

Keystroke progression graph

Lists

Unordered lists

Use -, *, or + as bullet markers. The marker must be followed by a space.

Syntax
- Node.js 18+
- PostgreSQL 14+
- Docker (optional)
Rendered
  • Node.js 18+
  • PostgreSQL 14+
  • Docker (optional)

Ordered lists

Use numbers followed by a period. Each item gets its own number.

Syntax
1. Clone the repository
2. Install dependencies
3. Copy the env file
4. Start the database
5. Run the server
Rendered
  1. Clone the repository
  2. Install dependencies
  3. Copy the env file
  4. Start the database
  5. Run the server

Nested lists

Indent with two or four spaces to create nested items.

Syntax
- Backend
  - FastAPI
  - PostgreSQL
- Frontend
  - Next.js
  - Tailwind CSS
Rendered
  • Backend
    • FastAPI
    • PostgreSQL
  • Frontend
    • Next.js
    • Tailwind CSS

Task lists (GitHub Flavored Markdown)

Task lists are one of the most useful features in GitHub Flavored Markdown. They render as interactive checkboxes in GitHub issues, pull requests, and project descriptions.

Syntax
- [x] Add authentication
- [x] Set up the database
- [ ] Write tests
- [ ] Deploy to staging
Rendered
  • Add authentication
  • Set up the database
  • Write tests
  • Deploy to staging

Code

Inline code

Wrap code in single backticks for inline formatting. Use it for variable names, file paths, commands, and short snippets.

Syntax
Run `npm install` before starting the server. The config lives in `src/config.ts`.
Rendered

Run npm install before starting the server. The config lives in src/config.ts.

Code blocks

Use triple backticks to create a code block. Add the language name after the opening backticks to enable syntax highlighting. This is one of the most visible improvements you can make to your documentation.

Syntax
```python
def greet(name: str) -> str:
    return f"Hello, {name}!"

print(greet("world"))
```
Rendered
def greet(name: str) -> str:
    return f"Hello, {name}!"

print(greet("world"))

Supported languages include: python, javascript, typescript, bash, sql, json, yaml, go, rust, java, and many more.

Diff blocks

Use diff as the language to show additions and removals. Prefix lines with + for additions and - for removals.

Syntax
```diff
- return user.name
+ return user.display_name or user.name
```
Rendered
- return user.name
+ return user.display_name or user.name

Diff blocks are most useful in pull request descriptions and changelogs. The clearer your commit messages, the more context your diffs carry. Git Commit Messages guide.

Want to see syntax applied to real projects? The full course walks through production READMEs end to end.Take the course →

Tables

Tables use pipe characters (|) as column separators. The second row contains the alignment markers: --- for left (default), :---: for center, ---: for right.

Syntax
| Command | Description |
|---------|-------------|
| `npm install` | Install dependencies |
| `npm run dev` | Start development server |
| `npm test` | Run tests |
| `npm run build` | Build for production |
Rendered
CommandDescription
npm installInstall dependencies
npm run devStart development server
npm testRun tests
npm run buildBuild for production

You do not need to align the pipes manually. Markdown renderers ignore the extra whitespace.

Blockquotes

Use > to create a blockquote. Blockquotes are useful for callouts, warnings, notes, and quoting other documents.

Syntax
> **Note**
> This feature requires Node.js 18 or later.

> **Warning**
> Running this command in production will drop all data.
Rendered

Note This feature requires Node.js 18 or later.

Warning Running this command in production will drop all data.

GitHub supports styled alert blockquotes using [!NOTE], [!WARNING], [!TIP], [!IMPORTANT], and [!CAUTION] inside the blockquote.

Syntax
> [!WARNING]
> Running this command in production will drop all data.
Rendered

[!WARNING] Running this command in production will drop all data.

GitHub Flavored Markdown

GitHub Flavored Markdown (GFM) extends standard Markdown with features specifically useful for developer workflows.

Autolinked references

On GitHub, certain references are automatically linked without any Markdown syntax. This makes pull request descriptions and issue comments much more scannable.

SyntaxResult
#123Links to issue or PR #123
user/repo#123Links to issue or PR in another repo
@usernameMentions a user
SHA1 hash (7+ chars)Links to a commit

These references are most useful in pull request descriptions and review comments. code review comments guide.

Collapsible sections

Use the HTML <details> element to create collapsible sections. This is useful for long outputs, stack traces, or configuration examples that would clutter the main text.

Syntax
<details>
<summary>Full stack trace</summary>

```
Error: Cannot read properties of undefined
    at getUserName (index.js:12)
    at main (index.js:34)
```

</details>
Rendered
Full stack trace
Error: Cannot read properties of undefined
    at getUserName (index.js:12)
    at main (index.js:34)

Footnotes

Footnotes are useful for adding references or clarifications without cluttering the main text.

Syntax
This feature is experimental.[^1]

[^1]: Experimental features may change in future releases.
Rendered

This feature is experimental.1

Footnotes

  1. Experimental features may change in future releases. ↩

GFM features like these are covered in depth with real repository examples in the full course.Take the course →

Badges

Badges are the fastest way to communicate project health at a glance. Browse all available badges at shields.io/badges.

Syntax
![Coverage](https://codecov.io/gh/user/repo/branch/main/graph/badge.svg)

![Version](https://img.shields.io/npm/v/your-package)

![License](https://img.shields.io/badge/license-MIT-blue)
Rendered

Coverage

Version

License

README best practices

A README is the front door of your project. When someone lands on your repository, they spend about 30 seconds scanning the README before deciding whether to read further. Here is the structure that makes those 30 seconds count.

Structure every README has

1
Title and one-sentence description
The project name as H1, then one sentence explaining what it does and who it is for.
2
Badges
Build status, test coverage, version, license. Put them right after the title for instant credibility.
3
Installation
Copy-pasteable commands. Assume nothing about the reader's setup. Specify the exact version requirements.
4
Usage
A code example showing the most common case. Add more examples for different scenarios.
5
Configuration
A table of environment variables or config options with their defaults and descriptions.
6
Contributing
How to open issues, run tests, and submit pull requests. Link to a CONTRIBUTING.md if it gets long.
7
License
One line naming the license and linking to the LICENSE file.

Three rules for readable documentation

Document the why, not just the what
Code already shows what it does. Documentation explains why a decision was made: 'We use polling instead of webhooks because the third-party API does not support webhooks.'
Keep it scannable
Use headers, bullet points, and short paragraphs. Most readers scan before they read. If your documentation is a wall of text, it will not be read.
Update it when the code changes
Outdated documentation is worse than no documentation: it wastes time. Add a step to your definition of done: update the README when behavior changes.

Once your README skills are solid, the same principles apply to longer technical documents. Writing a design doc in English.

The full course shows how to build this structure from scratch for different types of projects.Take the course →

Quick reference

SyntaxResult
# H1 / ## H2 / ### H3Headers
**text**Bold
*text*Italic
~~text~~Strikethrough
[text](url)Link
![alt](url)Image
- itemUnordered list item
1. itemOrdered list item
- [x] taskChecked task list item
- [ ] taskUnchecked task list item
`code`Inline code
```lang\ncode\n```Code block with syntax highlighting
> textBlockquote
| col | col |Table row
---Horizontal rule

One more thing: Mermaid diagrams

GitHub renders Mermaid diagrams natively inside Markdown code blocks. That means you can add flowcharts, sequence diagrams, and state diagrams to your README with nothing but code — no image exports, no external tools. Here are four examples from a real project:

Flowchart
Flowchart
Sequence diagram
Sequence diagram
State diagram
State diagram
State diagram (dark theme)
State diagram (dark theme)

The full course covers exactly how to add diagrams like these to your READMEs — including the syntax, the diagram types, and how to make them look good.

Markdown Documentation That Gets You Noticed as a Developer — Udemy course
Take it further

Markdown Documentation That Gets You Noticed as a Developer

Go beyond the syntax and learn how to structure documentation that actually gets read: READMEs that make your projects stand out, changelogs that communicate clearly, and writing habits that make you the developer teams trust with documentation.

5.0 ★by Roxana Lafuente
View on Udemy →
Roxana Lafuente

Written by

Roxana Lafuente

Lingua-e's founder

Roxana Lafuente is a software engineer with 8+ years of experience. At the beginning of her career, even though she had already passed the First Certificate in English, she still froze every time she had to speak up in the daily standup. That was a gap nobody was fixing. After 2,000+ standups, she figured out what actually builds fluency: practice that looks like your real work. She built Lingua-e so other developers wouldn't have to take the long road to feel confident working in an international development environment.

← Tutorials