markdown-syntax-fundamentals

Use when writing or editing markdown files. Covers headings, text formatting, lists, links, images, code blocks, and blockquotes.

⭐47stars🔀5forks📁View on GitHub🕐Updated Jan 2, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive toolkit for mastering Markdown syntax, enabling the creation of professional, well-structured documents. It covers everything from basic text formatting and hierarchical headings to advanced elements like syntax-highlighted code blocks, task lists, and internal anchors, ensuring high-quality documentation standards.

Use Cases

  • Technical Documentation: Streamline the creation and editing of README.md files, API documentation, and project wikis with consistent styling.
  • Content Drafting: Efficiently draft blog posts, newsletters, and web content in Markdown for seamless conversion to HTML or CMS platforms.
  • Knowledge Management: Organize internal knowledge bases and personal notes using clear hierarchies, nested lists, and cross-references.
  • Project Tracking: Utilize GitHub-flavored task lists and blockquotes to manage project requirements and team communications effectively.
namemarkdown-syntax-fundamentals
descriptionUse when writing or editing markdown files. Covers headings, text formatting, lists, links, images, code blocks, and blockquotes.

Markdown Syntax Fundamentals

Core markdown syntax for creating well-structured documents.

Headings

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

Heading Best Practices

  • Use a single H1 (#) per document as the title
  • Don't skip heading levels (H2 to H4)
  • Keep headings concise and descriptive
  • Use sentence case or title case consistently

Text Formatting

Emphasis

*italic* or _italic_
**bold** or __bold__
***bold italic*** or ___bold italic___
~~strikethrough~~

Inline Code

Use `backticks` for inline code like `const x = 1`

Lists

Unordered Lists

- Item one
- Item two
  - Nested item
  - Another nested item
- Item three

* Alternative marker
+ Also works

Ordered Lists

1. First item
2. Second item
   1. Nested numbered
   2. Another nested
3. Third item

Task Lists (GitHub Flavored)

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task
[Link text](https://example.com)
[Link with title](https://example.com "Title text")
[Link text][reference-id]

[reference-id]: https://example.com "Optional title"
<https://example.com>
<email@example.com>
[Jump to section](#section-heading)

Anchor IDs are auto-generated from headings:

  • Lowercase
  • Spaces become hyphens
  • Special characters removed

Images

Basic Images

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

Reference Images

![Alt text][image-id]

[image-id]: path/to/image.png "Optional title"

Linked Images

[![Alt text](image.png)](https://example.com)

Code Blocks

Fenced Code Blocks

```javascript
function hello() {
  console.log("Hello, World!");
}
```

Common Language Identifiers

  • javascript / js
  • typescript / ts
  • python / py
  • bash / shell / sh
  • json / yaml
  • html / css
  • sql
  • markdown / md

Indented Code Blocks

    // Four spaces or one tab
    function example() {
      return true;
    }

Blockquotes

Basic Blockquotes

> This is a blockquote.
> It can span multiple lines.

> Blockquotes can contain
>
> Multiple paragraphs.

Nested Blockquotes

> Outer quote
>> Nested quote
>>> Deeply nested

Blockquotes with Other Elements

> ## Heading in blockquote
>
> - List item
> - Another item
>
> ```code block```

Horizontal Rules

---
***
___

Use three or more hyphens, asterisks, or underscores.

Escaping Characters

\* Not italic \*
\# Not a heading
\[Not a link\]
\`Not code\`

Characters that can be escaped: \ ` * _ { } [ ] ( ) # + - . ! |

Line Breaks

Line one with two trailing spaces
Line two (hard break)

Line one

Line two (paragraph break)

Best Practices

  1. Consistent formatting: Pick a style and stick to it
  2. Blank lines: Add blank lines before and after:
    • Headings
    • Code blocks
    • Lists
    • Blockquotes
  3. Line length: Consider wrapping at 80-120 characters for readability
  4. Alt text: Always provide meaningful alt text for images
  5. Link text: Use descriptive link text, not "click here"
  6. Code highlighting: Always specify language for fenced code blocks