Most developers know the basics: **bold**, # heading, [link](url). But Markdown has features that even experienced writers overlook. Here are the ones worth knowing.
Fenced code blocks with syntax highlighting
The basic syntax:
```
javascript
const greeting = 'Hello, world!';
console.log(greeting);
```
```
`
The language hint after the opening backticks enables syntax highlighting in GitHub, GitLab, Dev.to, Notion, and most Markdown renderers. Common language identifiers: `javascript`, `typescript`, `python`, `bash`, `sql`, `yaml`, `json`, `css`, `html`, `go`, `rust`.
For terminal output: use `bash` or `shell`. For file paths and commands: use `console` or `text`.
## Task lists (GitHub Flavored Markdown)
```markdown
- [x] Set up the project
- [x] Add authentication
- [ ] Write tests
- [ ] Deploy to staging
```
Renders as interactive checkboxes on GitHub and GitLab. In a README, this creates a visual progress indicator. In issues, the checkboxes are actually interactive.
## Collapsible sections in GitHub Markdown
Wrap content in `<details>` for a collapsible section — useful for long code examples, output, or supplementary information in READMEs and issues:
```markdown
<details>
<summary>Click to expand: Full error output</summary>
```
Error: ENOENT: no such file or directory, open '/etc/config.yaml'
at Object.openSync (fs.js:462:3)
```plaintext
The full stack trace was 200 lines.
</details>
```
GitHub renders this as a collapsed "Click to expand" section.
## Definition lists (non-standard but widely supported)
Some parsers (kramdown, Pandoc) support definition lists:
```markdown
Term 1
: Definition of term 1
Term 2
: First definition
: Second definition
```
This is not in the standard Markdown spec but is supported by Jekyll/GitHub Pages, some static site generators, and can be useful in documentation.
## Tables
```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1 | Value | Value |
| Row 2 | Value | Value |
```
Column alignment:
```markdown
| Left | Center | Right |
|:---------|:-------:|---------:|
| aligned | aligned | aligned |
```
The `:` in the separator row controls alignment: `:---` = left, `:---:` = center, `---:` = right.
**Tip**: tables are valid HTML inside Markdown. If you need complex tables (merged cells, complex styles), use raw HTML. It will be preserved by most parsers.
## Footnotes (extended Markdown)
```markdown
This is a claim that needs a source.[^1]
[^1]: Source: Research paper title, Author, 2024.
```
Supported by Pandoc, GitHub, and many documentation tools. Footnote references are converted to superscript numbers that link to the footnote definition.
## Hard line breaks
In standard Markdown, a single newline in text produces no line break in the output. To force a line break:
- End the line with two spaces + newline (invisible, fragile)
- Use `\` at the end of the line (GFM only)
- Use a blank line to start a new paragraph (most reliable)
If you're writing prose and want visual paragraphs, use blank lines between them — they're semantically meaningful and universally supported.
## Escaping Markdown characters
Use a backslash to escape characters that would otherwise be interpreted as Markdown:
```markdown
\*This is not italic\*
\# This is not a heading
\[This is not a link\]
```
Useful when writing about Markdown itself or when your text naturally contains these characters.
## Inline HTML
Standard Markdown allows inline HTML. This is useful for:
```markdown
<kbd>Ctrl</kbd> + <kbd>S</kbd> to save
<mark>highlighted text</mark>
<sub>subscript</sub> and <sup>superscript</sup>
<br> for forced line breaks that work everywhere
```
These render in GitHub READMEs, documentation sites, and most Markdown processors. Don't overuse it — if you're writing a lot of raw HTML, you may want a different format.
## Converting Markdown to HTML
To see exactly how your Markdown will render — or to generate HTML from a Markdown file for embedding in a website — the [Markdown to HTML Converter](https://snappytools.app/markdown-to-html/) renders GitHub Flavored Markdown in the browser. Useful for previewing complex tables, code blocks, and task lists before committing.
## Tips for writing Markdown that renders everywhere
- Use fenced code blocks with language hints (not 4-space indentation) — wider support
- Keep table cells simple — avoid line breaks or complex content inside cells
- Test your README on GitHub's actual renderer before finalising (not just your local editor preview)
- Use ATX-style headings (`# Heading`) rather than setext style (`Heading\n=====`) — more consistent across parsers
- Prefer `*` for bullet lists and `**bold**` over `__bold__` — fewer edge cases
---
Markdown's strength is that 90% of what you write renders identically everywhere. The remaining 10% — footnotes, definition lists, collapsible sections — varies by parser. For documentation you control the stack for, use them freely. For content that will live on external platforms (GitHub, Dev.to, Notion), test or stick to the GFM subset.
Top comments (0)