Markdown Hacks: Tips, Tricks, and Workarounds

Table of Contents

Markdown does not generate a table of contents automatically, but you can build one manually using internal links. Each link points to a heading anchor. Some processors like GitHub auto-generate heading IDs from the heading text.

## Table of Contents

- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Advanced Usage](#advanced-usage)

## Introduction

Your content here...

GitHub auto-generates heading IDs by lowercasing and replacing spaces with hyphens. Some static site generators offer plugins for automatic TOC generation.

Underline

Markdown has no native underline syntax because underlined text is easily confused with hyperlinks. The workaround is to use the HTML <ins> tag, which semantically represents inserted text and renders as underlined.

<ins>This text is underlined.</ins>

Regular text with an <ins>underlined word</ins> inside.

Works on GitHub, GitLab, and most processors that allow inline HTML. Some strict processors may strip HTML tags.

Indent and Tab

Standard markdown does not support arbitrary indentation. Leading spaces are usually ignored or interpreted as code blocks. You can use non-breaking spaces or nested blockquotes as workarounds.

    This line is indented with non-breaking spaces.

> First level indent
>> Second level indent
>>> Third level indent

The &nbsp; approach works in HTML-rendering processors. Nested blockquotes are a visual trick and add quote styling.

Center Text

Markdown does not have alignment syntax. To center text, wrap it in an HTML div or paragraph tag with an align attribute. This works in most processors that permit inline HTML.

<div align="center">

This text is centered.

**Bold centered text**

</div>

<p align="center">A centered paragraph.</p>

Works on GitHub README files and most HTML-permitting processors. Leave blank lines between the div tags and the markdown content inside.

Color Text

Markdown has no built-in support for colored text. You can use HTML span tags with inline styles to apply color. Note that GitHub strips style attributes from markdown files, so this works best in HTML-rendering contexts.

<span style="color: red">This text is red.</span>

<span style="color: #1e90ff">This text is dodger blue.</span>

<span style="color: green">**Green bold text**</span>

GitHub README files strip inline styles for security. This works in HTML email, static site generators, and processors that support inline styles.

Comments

Use HTML comment syntax to add notes that will not appear in the rendered output. Comments are useful for leaving instructions for collaborators or temporarily hiding content.

<!-- This is a comment. It will not appear in the output. -->

Some visible text.

<!-- TODO: Add more examples here -->

More visible text.

Works in virtually all markdown processors. Comments are visible in the raw source but hidden in the rendered output.

Admonitions and Callouts

Admonitions are highlighted blocks used for tips, warnings, and notes. Markdown does not have a standard syntax for these, but GitHub supports a blockquote-based format with special markers. Other platforms use different conventions.

> [!NOTE]
> This is a note callout on GitHub.

> [!WARNING]
> This is a warning callout on GitHub.

> [!TIP]
> This is a tip callout on GitHub.

> [!IMPORTANT]
> This is an important callout on GitHub.

> [!CAUTION]
> This is a caution callout on GitHub.

The [!TYPE] syntax is GitHub-specific. Obsidian, MkDocs, and other tools have their own callout formats.

Image Sizing

Standard markdown image syntax does not support width or height attributes. Use an HTML img tag to control image dimensions. This gives you full control over display size.

<!-- Standard markdown image (no size control) -->
![Logo](https://example.com/logo.png)

<!-- HTML image with width -->
<img src="https://example.com/logo.png" alt="Logo" width="300">

<!-- HTML image with width and height -->
<img src="https://example.com/logo.png" alt="Logo" width="300" height="200">

The HTML img tag works on GitHub, GitLab, and most processors. Always include an alt attribute for accessibility.

Link Targets

Markdown links always open in the current tab. To open a link in a new tab, use an HTML anchor tag with target="_blank". Adding rel="noopener noreferrer" is a security best practice.

<!-- Standard markdown link (same tab) -->
[Example](https://example.com)

<!-- HTML link that opens in a new tab -->
<a href="https://example.com" target="_blank" rel="noopener noreferrer">
  Example (new tab)
</a>

Works in processors that allow inline HTML. GitHub strips target attributes from links in markdown files for security.

Symbols and Special Characters

You can insert special characters using HTML entities. This is useful for characters that markdown would otherwise interpret as formatting syntax, or for symbols not available on your keyboard.

© Copyright symbol
® Registered trademark
™ Trademark
& Ampersand
< Less than
> Greater than
  Non-breaking space
— Em dash
→ Right arrow: →
✓ Check mark: ✓

HTML entities work in most markdown processors. You can also paste Unicode characters directly into your markdown.

Table Formatting

Markdown tables do not natively support line breaks or multi-line content in cells. You can use the HTML <br> tag for line breaks within a cell, or switch to full HTML tables for complex layouts.

| Feature | Description |
| ------- | ----------- |
| Line breaks | Use the HTML br tag<br>to break lines in a cell |
| Long content | Keep the cell content<br>readable with breaks |

<!-- For complex tables, use HTML directly -->
<table>
  <tr>
    <th>Name</th>
    <th>Details</th>
  </tr>
  <tr>
    <td>Item 1</td>
    <td>
      First line<br>
      Second line
    </td>
  </tr>
</table>

The <br> tag works in most GFM-compatible processors. For complex tables, consider using our table generator tool.

Videos

Markdown does not support video embedding directly. The most common workaround is to display a thumbnail image that links to the video. On GitHub, you can also use an HTML video tag for uploaded video files.

<!-- Linked thumbnail (works everywhere) -->
[![Video Title](https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg)](https://www.youtube.com/watch?v=VIDEO_ID)

<!-- HTML video tag (GitHub supports this for uploaded files) -->
<video src="https://example.com/video.mp4" width="400" controls>
  Your browser does not support the video tag.
</video>

The linked thumbnail approach works in all processors. The video tag is only supported where inline HTML is allowed.

Collapsible Sections

Use the HTML details and summary elements to create expandable/collapsible sections. The summary text is always visible, and clicking it toggles the hidden content. This is great for FAQs, long code examples, or optional details.

<details>
<summary>Click to expand</summary>

This content is hidden by default.

You can put **any markdown** here:
- Lists
- Code blocks
- Images

</details>

<details>
<summary>Another collapsible section</summary>

More hidden content here.

</details>

Works on GitHub, GitLab, and most modern processors. Leave a blank line after the summary tag before your markdown content.

Frequently Asked Questions