Markdown Authoring Skill

This skill ensures markdown documents follow best practices for syntax, structure, accessibility, and content quality.

Markdown Flavors

This project follows CommonMark with GitHub Flavored Markdown (GFM) extensions:

Document Structure

Single H1 Rule

Every document should have exactly one H1 heading as the title:

# Document Title

Content begins here...

## First Section

## Second Section

Heading Hierarchy

Follow logical heading levels - never skip levels:

# Title (H1)

## Major Section (H2)

### Subsection (H3)

#### Detail (H4)

## Another Major Section (H2)

Avoid:

# Title

### Skipped H2!  <!-- BAD: Jumped from H1 to H3 -->

Document Template

# Document Title

Brief description or introduction paragraph.

## Table of Contents

- [Section One](#section-one)
- [Section Two](#section-two)
- [Section Three](#section-three)

## Section One

Content here.

## Section Two

Content here.

## Section Three

Content here.

## Related

- [Link to related doc](./related.md)

YAML Frontmatter

Basic Frontmatter

Add metadata at the top of documents:

---
title: Document Title
description: Brief description for SEO and previews
author: Author Name
date: 2024-01-15
tags:
  - documentation
  - guide
---

# Document Title

Content begins after frontmatter.

Common Frontmatter Fields

title

"Getting Started Guide"

description

"Learn how to..."

author

"Jane Doe"

date

2024-01-15

updated

2024-03-20

tags

[guide, tutorial]

draft

true

false

order

1

2

3

Blog Post Frontmatter

---
title: How to Build Web Components
description: A comprehensive guide to creating custom elements
author: Jane Doe
date: 2024-01-15
tags:
  - javascript
  - web-components
  - tutorial
image: /images/blog/web-components.jpg
---

Documentation Frontmatter

---
title: API Reference
description: Complete API documentation
sidebar_position: 3
---

Text Formatting

Emphasis

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

Prefer asterisks (

*

_

Inline Code

Use backticks for code, commands, filenames, and technical terms:

Run `npm install` to install dependencies.
Edit the `package.json` file.
The `useState` hook manages state.

Links

Inline Links

[Link text](https://example.com)
[Link with title](https://example.com "Title text")

Reference Links

For repeated URLs or cleaner text:

Read the [documentation][docs] for more details.
See the [API reference][api] for endpoints.

[docs]: https://example.com/docs
[api]: https://example.com/api

Internal Links

Use relative paths for internal links:

See [Getting Started](./getting-started.md)
Read the [API docs](../api/reference.md)
Jump to [Installation](#installation)

Anchor Links

Link to headings using lowercase, hyphenated IDs:

## Installation Steps

...

See [Installation Steps](#installation-steps) above.

Accessible Link Text

Use descriptive link text:

<!-- BAD -->
[Click here](./guide.md) for the guide.
For more info, [read this](./docs.md).

<!-- GOOD -->
Read the [installation guide](./guide.md).
See the [API documentation](./docs.md) for details.

Images

Basic Syntax

![Alt text describing the image](./images/screenshot.png)

Images with Titles

![Dashboard screenshot](./images/dashboard.png "The main dashboard view")

Reference Images

![Application logo][logo]

[logo]: ./images/logo.png "Application Logo"

Alt Text Guidelines

Write meaningful alt text:

<!-- BAD -->
![](./chart.png)
![image](./chart.png)
![chart](./chart.png)

<!-- GOOD -->
![Monthly revenue chart showing 25% growth](./chart.png)
![Error dialog with retry and cancel buttons](./error-dialog.png)

When to Use Empty Alt

For decorative images only:

![](./decorative-divider.png)

Code Blocks

Fenced Code Blocks

Always specify the language for syntax highlighting:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

Common Language Identifiers

javascript

js

typescript

ts

html

css

json

yaml

bash

shell

python

py

markdown

md

text

plaintext

Code Block with Filename

Use a comment or heading to indicate the file:

**`src/utils.js`**
```javascript
export function formatDate(date) {
  return date.toISOString();
}
```

Diff Syntax

Show changes with diff highlighting:

```diff
- const old = "value";
+ const updated = "new value";
```

Lists

Unordered Lists

Use hyphens consistently:

- First item
- Second item
- Third item

Ordered Lists

1. First step
2. Second step
3. Third step

Nested Lists

Indent with 2 or 4 spaces (be consistent):

- Parent item
  - Child item
  - Another child
    - Grandchild
- Another parent

Task Lists (GFM)

- [x] Completed task
- [ ] Incomplete task
- [ ] Another todo

List Content

For multi-paragraph list items:

1. First step

   Additional details about the first step.
   Can span multiple lines.

2. Second step

   More information here.

Tables

Basic Tables

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Column Alignment

| Left | Center | Right |
|:-----|:------:|------:|
| L    | C      | R     |
| L    | C      | R     |

Table Best Practices

• Keep tables simple - complex data may need different format
• Use alignment for numeric data (right-align numbers)
• Keep cell content concise
• Consider using lists for very long content

Blockquotes

Basic Blockquotes

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

Nested Blockquotes

> Outer quote
>
> > Nested quote

Callouts/Admonitions

Use blockquotes with emphasis for callouts:

> **Note:** Important information here.

> **Warning:** Be careful about this.

> **Tip:** Helpful suggestion here.

Or with emoji for visual distinction:

> 📝 **Note:** Information to highlight.

> ⚠️ **Warning:** Proceed with caution.

> 💡 **Tip:** Helpful suggestion.

> 🚨 **Danger:** Critical warning.

Horizontal Rules

Use three hyphens with blank lines:

Content above.

---

Content below.

Escaping

Escape special characters with backslash:

\*not italic\*
\# not a heading
\[not a link\]

Line Breaks

Paragraphs

Separate paragraphs with blank lines:

First paragraph.

Second paragraph.

Hard Line Breaks

Use two trailing spaces or

<br>

Line one
Line two (note two spaces above)

Or use:
Line one<br>
Line two

Accessibility

Heading Structure

Screen readers use headings for navigation:

• Use one H1 per document
• Don't skip heading levels
• Use headings for structure, not styling

Descriptive Links

<!-- Screen reader announces: "link, click here" - unhelpful -->
[Click here](./guide.md)

<!-- Screen reader announces: "link, installation guide" - clear -->
[Installation guide](./guide.md)

Image Alt Text

• Describe the content and function
• Keep it concise but meaningful
• Use empty alt for decorative images

Tables

• Use header rows
• Keep structure simple
• Provide context before complex tables

Code Blocks

• Specify language for syntax highlighting
• Provide context before code examples
• Explain what code does, not just show it

Content Quality

Integration with Content Skills

The

content-writer

• Run spell check:

  npm run lint:spelling

• Run grammar check:

  npm run lint:grammar

• Check reading level for technical vs general content

Consistency

• Use consistent heading capitalization (Title Case or Sentence case)
• Use consistent list markers (hyphens, not mixed)
• Use consistent code fence style (backticks, not indentation)
• Use consistent emphasis style (asterisks, not underscores)

File Naming

README.md           # Repository root
CHANGELOG.md        # Version history
CONTRIBUTING.md     # Contribution guide
docs/               # Documentation folder
  getting-started.md
  api-reference.md
  troubleshooting.md

Markdown Checklist

Before finalizing markdown documents:

Structure

• Single H1 as document title
• Logical heading hierarchy (no skipped levels)
• Table of contents for long documents
• Frontmatter with appropriate metadata

Content

• Descriptive link text (not "click here")
• Alt text for all images (except decorative)
• Language specified for code blocks
• Spell check passed

Formatting

• Consistent list markers
• Consistent emphasis style
• Proper table alignment
• Blank lines around blocks (headings, code, lists)

Links

• Internal links use relative paths
• External links work
• Anchor links match heading IDs

Common Mistakes

Related Skills

content-writer

i18n

git-workflow