Little Stuff in Markdown Developers Always Forget

Every developer has experienced that moment: you're writing documentation, a README, or a technical blog post, and suddenly you can't remember the exact syntax for something you use almost every day. Is it two asterisks or two underscores for bold? How do you escape that backtick inside a code block? Why isn't my link working?

Markdown has become the de facto standard for technical documentation, README files, and content across the modern web. Its simplicity is its power--but that simplicity also means certain syntax details slip from memory between uses. This guide covers the markdown elements, HTML integrations, and best practices that developers consistently forget.

Modern web development emphasizes clean, maintainable code and documentation. Just as we write performant JavaScript and optimized CSS, our documentation should follow consistent patterns that scale. Whether you're contributing to open source, documenting internal APIs, or writing technical blog posts, mastering these markdown fundamentals will improve your documentation quality and reduce time spent hunting for syntax answers.

For teams building comprehensive documentation systems, integrating markdown workflows with your /services/web-development/ infrastructure ensures consistent experiences across all technical content.

The Fundamentals Worth Remembering

Headings and Document Structure

Headings form the backbone of any markdown document, providing both visual hierarchy and accessibility structure for screen readers. The most common mistake developers make with headings is inconsistent spacing or skipping heading levels entirely.

# Heading Level 1
## Heading Level 2
### Heading Level 3
#### Heading Level 4
##### Heading Level 5
###### Heading Level 6

Google's style guide emphasizes using ATX-style headings (the hash symbol format) rather than the underline format (=== or ---) because underlines are ambiguous--is that a level one or level two heading? The hash format is explicit and consistent.

Equally important is maintaining unique, descriptive heading names throughout your document. If you have multiple sections that could use a "Summary" heading, rename them to be specific: "Project Summary" and "Implementation Summary." This ensures automatically-generated anchor links are intuitive and clear.

Spacing matters more than most developers realize. Always include a blank line before and after headings. This improves readability in the source markdown and ensures consistent rendering across different markdown processors.

Emphasis and Text Formatting

The battle between asterisks and underscores for emphasis syntax is one of the most frequently forgotten details. Both work, but asterisks provide better cross-processor compatibility when emphasizing the middle of a word:

Standard emphasis:
**Bold text**
*Italic text*

Middle-of-word emphasis (use asterisks for compatibility):
Word**middle**emphasis

For combined bold and italic, you have multiple valid options. All of these render identically in most processors:

***Bold and italic***
**_Bold and italic_**
__*Bold and italic*__

The key is consistency within your document. Pick one style and use it throughout. When documenting CSS properties like text transformations, consistent formatting helps readers quickly identify the concepts you're explaining.

Lists That Actually Render Correctly

Ordered and unordered lists seem simple, but several nuances trip up developers regularly. First, the numbers in ordered lists don't actually matter--markdown processors will renumber them sequentially regardless of what you type:

1. First item
1. Second item
1. Third item

Renders as: 1, 2, 3. This "lazy numbering" makes maintenance easier since you don't need to renumber after inserting an item.

For nested lists, Google recommends a 4-space indent for consistent rendering of wrapped text:

1. First item with explanation that wraps to multiple lines
 1. Nested item
 2. Another nested item
2. Second top-level item

Unordered lists can use -, *, or +, but pick one and stick with it. Mixing delimiters in the same document looks inconsistent and can cause rendering issues in some processors.

Code Formatting: Beyond the Backtick

Inline code uses single backticks, but the moment you need to include a backtick within inline code, you're in trouble unless you remember the escape strategy:

Inline code: `console.log()`

Escaping backticks: Use double backticks `` `inside` ``

For multi-line code blocks, fenced code blocks with triple backticks are strongly preferred over indented code blocks. Why? Three key reasons:

1. You can specify the language for syntax highlighting
2. The start and end of the code block are unambiguous
3. They're easier to search for in code search tools

function greet(name) {
 console.log(`Hello, ${name}!`);
}

When code blocks appear within lists, they need additional indentation to maintain list structure:

1. First list item:

 ```bash
 npm install package-name

2. Second list item

Proper code formatting is essential for developer documentation. When building [/services/web-development/](/services/web-development/) projects that include API documentation or technical guides, consistent code block formatting improves the developer experience significantly.

Links and References

The basic link syntax is straightforward, but several forgotten details improve link quality:

Basic link: [Title](https://example.com)

Link with title (shows on hover):
[Title](https://example.com "Optional title")

For long URLs that disrupt document readability, reference-style links keep source documents clean:

See the [documentation][docs] for more information.

[docs]: https://example.com/documentation/that/is/very/long/and/would/disrupt/readability

Google's style guide recommends using reference links when the destination URL is long enough to disrupt text flow, but avoid them for short links where inline format is more readable.

Images and Media

Images follow link syntax with an exclamation mark prefix:

![Alt text](image.jpg)
![Alt text](image.jpg "Optional title")

The alt text is critical for accessibility--it describes the image for screen readers and displays when the image fails to load. Make it descriptive and meaningful.

Tables in Markdown

Tables are part of extended markdown syntax supported by most processors:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1 | Data | More |
| Row 2 | Data | More |

Alignment is specified in the header separator row:

| Left Align | Center Align | Right Align |
|:-----------|:------------:|:------------:|
| Data | Data | Data |

Google's style guide emphasizes keeping tables compact and readable. Avoid tables with excessive columns or cells containing long paragraphs--these are signs the content might be better presented as a list or prose. Tables work best for structured data comparisons, such as when documenting different CSS properties or JavaScript methods side-by-side.

HTML Integration Within Markdown

One of markdown's most powerful yet underutilized features is the ability to embed HTML directly. This provides escape hatches when markdown's syntax falls short:

You can write markdown normally, then drop into HTML for specific needs:

<div class="custom-component">
 <p>This paragraph has <span style="color: blue">custom styling</span></p>
</div>

Back to markdown again.

HTML integration is particularly valuable for:

• Custom styling that markdown can't express
• Embedding third-party widgets or components
• Creating complex layouts within documentation
• Adding interactive elements

However, Google's style guide warns that HTML reduces portability and limits tool integrations. Prefer markdown syntax wherever possible, using HTML only when necessary.

Block-level HTML elements (divs, tables, pre blocks) need blank lines separating them from surrounding markdown content:

Previous markdown paragraph.

<div class="warning">
 <p>This is an HTML block within markdown.</p>
</div>

Following markdown paragraph.

When working on advanced documentation projects that combine markdown with custom components, understanding the balance between pure markdown and HTML integration becomes crucial for maintaining both flexibility and portability.

Common Pitfalls and Edge Cases

The Trailing Whitespace Trap

The CommonMark specification states that two spaces at the end of a line should create a <br /> line break. In practice, this is one of the most problematic markdown features because trailing whitespace is invisible in most editors and often stripped by auto-formatters.

Google's style guide recommends avoiding trailing whitespace entirely. Instead, use a trailing backslash for explicit line breaks:

First line of text.\
Second line of text.

However, the best practice is often restructuring content to avoid needing explicit line breaks entirely--paragraphs are separated by blank lines, which creates proper <p> tags.

Escaping Characters

When you need markdown syntax to appear literally rather than be rendered, escape the special character with a backslash:

\* This is not a list item, it's literal asterisks

\# This is not a heading, it's a literal hash

The characters that can be escaped include: \, backtick, *, _, {, }, [, ], <, >, (, ), #, +, -, ., !, |

Automatic Link False Positives

Angle brackets around URLs or email addresses automatically create links:

<https://example.com>
<[email protected]>

This is convenient but can create unwanted links when you mention a URL in passing. To prevent auto-linking, escape the angle brackets:

\<https://example.com\> (won't become a clickable link)

Heading ID Conflicts

Some markdown processors automatically generate heading IDs from heading text. If you need a custom ID (for cross-referencing):

### My Custom Heading {#my-custom-id}

This syntax is part of extended markdown and may not work in all processors. Understanding these edge cases helps prevent rendering issues when migrating documentation between different markdown processors or static site generators.

Best Practices for Developer Documentation

Document Structure and Layout

Following Google's documentation principles, every document benefits from a consistent structure:

# Document Title

Brief introduction (1-3 sentences).

[TOC] <!-- If your processor supports it -->

## Topic 1

Content for the first major section.

## Topic 2

Content for the second section.

## See Also

- [Link to related documentation](link)
- [Another resource](link)

The introduction should answer "what is this?" and "why would I use it?"--imagine a newcomer landing on your documentation page for the first time.

Code Examples That Work

Code examples should be copy-pasteable and include necessary context:

To install the package, run:

```bash
npm install @company/package

Then import it in your code:

import { something } from '@company/package';

**For command-line examples that users should copy directly, escape newlines with backslashes** to prevent line-wrapping issues:

```bash
npx command --flag --another-flag \
 --long-argument-that-would-otherwise-wrap

Performance Considerations for Documentation Sites

While markdown itself is just text, how you use it affects documentation site performance:

• Minimize nested code blocks: Excessive indentation creates deep DOM structures
• Use syntax highlighting efficiently: Some highlighters can slow page load
• Optimize images: Use appropriate formats and sizes for any embedded images
• Consider incremental rendering: For large documents, lazy-load sections

Modern static site generators like Next.js with MDX support optimize markdown rendering automatically, but being mindful of these factors helps when debugging performance issues.

Accessibility in Documentation

Accessibility often gets forgotten in documentation, but it's crucial:

• All images need descriptive alt text
• Links should have meaningful anchor text (not "click here")
• Code examples should have proper syntax highlighting for readability
• Tables need proper headers for screen reader navigation
• Color-coded warnings or notes should not rely solely on color

> **Note:** This is accessible because it has the "Note" label.
> Don't use color alone to convey meaning.

Building accessible documentation is part of inclusive web development practices. Teams focused on /services/web-development/ should ensure their documentation workflows include accessibility checks as a standard part of the content review process.

Common Errors to Avoid

• Missing spaces after hash symbols in headings
• Mixing unordered list delimiters (-, *, +)
• Using indented code blocks instead of fenced
• Forgetting blank lines around block elements
• Creating links with vague anchor text
• Leaving out alt text for images
• Using trailing whitespace for line breaks

---

Related Resources:

• CSS Transform Translate Not Working - Debug CSS transform issues
• Centering CSS Display Table Cell - CSS layout fundamentals
• The Many Ways to Include CSS in JavaScript Applications - Modern CSS integration patterns

Looking to improve your entire documentation workflow? Our /services/web-development/ team can help you build scalable documentation systems that maintain consistency across all your technical content.

Sources

• Markdown Guide - Basic Syntax
• Google Markdown Style Guide
• Markdown Guide - Cheat Sheet