Markdown Syntax Guide

Linking to External Resources

To open a link in a new browser window, use the target="_blank" attribute within an anchor tag. While standard HTML, some Markdown processors support extended syntax for this.

Standard HTML approach:

<a href="http://example.com/" target="_blank">Example Link</a>

Some Markdown extensions allow this syntax:

[link](url){:target="_blank"}

For more details, refer to Stack Overflow discussions on Markdown links.

Hiding Content with Details/Summary

You can use HTML's <details> and <summary> tags to create collapsible sections, useful for saving space in pull requests or detailed explanations.

<details>
  <summary>Click to reveal details</summary>
  <p>This content is hidden until the summary is clicked.</p>
</details>

Example:

<details>
  <summary>Click to reveal details</summary>
  <p>This content is hidden until the summary is clicked.</p>
</details>

See a live example on jsFiddle.

Resizing Images

Control the display size of images directly within your Markdown. This is particularly useful for adjusting image dimensions for better layout.

Using HTML:

<img src="images/img.png" width="100" alt="Descriptive Alt Text">

Some Markdown processors, like those used in Jekyll, support custom syntax:

![](images/img.png | width=100)
![](images/img.png =250x250)

Explore advanced image manipulation techniques at GitHub Gists and Stack Overflow.

Syntax Highlighting for Code Blocks

To illustrate command-line or shell commands with syntax highlighting, specify the language after the opening backticks. console is a common choice for shell commands.

$ ls -l

Example with highlighting:

$ ls -l

Other supported languages like bash or bat (for batch files) can also be used.

• Refer to GitHub's Linguist repository for a comprehensive list of supported languages.
• Learn more about syntax highlighting in Markdown at CodebaseHQ.

Creating Checkboxes

Task lists with checkboxes are a great way to track progress or create to-do items within your Markdown documents.

- [ ] Unchecked item
- [x] Checked item

Rendered example:

• Unchecked item
• Checked item

Using Callouts for Emphasis

Markdown supports callout blocks (often rendered as distinct colored boxes) to draw attention to important notes, warnings, or tips.

> [!NOTE]
> This is an important note that requires attention.

Rendered example:

[!NOTE]
This is an important note that requires attention.

GitHub Markdown also supports other types like [!WARNING], [!TIP], and [!IMPORTANT]. See GitHub Markdown Alerts for details.

Applying Strike-Through Text

To indicate text that is no longer accurate or relevant, use double tildes (~~) to apply a strike-through effect.

~~This text will be struck through.~~

Rendered example:

This text will be struck through.

Internal Document Linking

Create links to specific sections within the same Markdown document. This is invaluable for navigation, especially in longer documents or tables of contents. Spaces in headings are typically replaced with hyphens.

To link to a heading:

[Link to Section](#section-id)

For automatically generated IDs from headings:

# My Section Title

[Link to My Section](#my-section-title)

This is particularly useful for creating a table of contents. For numbered sections, the numbering is often included in the ID.

Example linking to sections:

• Linking to External Resources
• Hiding Content with Details/Summary

Further reading on internal linking: Stack Overflow on same-document links.

Using Footnotes

Add supplementary information or citations using footnotes. They appear at the bottom of the document, linked from the text.

Here is some text with a footnote.[^1]

[^1]: This is the content of the footnote.

Rendered example:

Here is some text with a footnote.^[1]

Incorporating Math Symbols with LaTeX

Markdown can render mathematical equations and symbols using LaTeX syntax, making it suitable for scientific and technical documentation.

Inline math:

$E = mc^2$

Rendered inline math: $E = mc^2$

Block math:

$$
\int_{-\infty}^\infty e^{-x^2} dx = \sqrt{\pi}
$$

Rendered block math:

$$ \int_{-\infty}^\infty e^{-x^2} dx = \sqrt{\pi} $$

Creating Line Breaks

To force a line break without starting a new paragraph, add two or more spaces at the end of a line.

First line.  
Second line.

Rendered example:

First line.
Second line.

External Resources and References

Explore these resources for deeper understanding and advanced usage of Markdown:

1. Daring Fireball - The original Markdown specification
2. Markdown Cheatsheet by adam-p
3. Markdown Cheat Sheet by Markdown Guide
4. Markdown Basic Syntax Guide
5. GitHub Markdown Alerts
6. Tips for Exceptional GitHub Writing