Learn-skills.dev markdown

Markdown syntax, formatting, and document authoring for docs, READMEs, and technical writing. Use when user mentions "markdown", "write README", "format markdown", "markdown table", "markdown links", "GFM", "GitHub flavored markdown", "markdown linting", "MDX", "markdown to HTML", "table of contents", "markdown badges", "markdown checklist", or authoring documentation in markdown.

install

source · Clone the upstream repo

git clone https://github.com/NeverSight/learn-skills.dev

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/1mangesh1/dev-skills-collection/markdown" ~/.claude/skills/neversight-learn-skills-dev-markdown && rm -rf "$T"

manifest: data/skills-md/1mangesh1/dev-skills-collection/markdown/SKILL.md

source content

Markdown Authoring Reference

Reference for markdown documents covering core syntax, GFM extensions, README patterns, technical docs, MDX, and linting. See

references/markdown-guide.md

for a syntax cheat sheet and

references/tech-writing-guide.md

for documentation structure.

1. Core Syntax

Headings

# H1 - Document Title (one per file)
## H2 - Major Section
### H3 - Subsection
#### H4 - Detail Level

Use ATX style (

), not Setext. Space after

. Never skip levels. One H1 per file.

Emphasis and Inline

*italic*    **bold**    ***bold italic***    ~~strikethrough~~
`inline code`    <kbd>Ctrl+C</kbd>    <sup>super</sup>    <sub>sub</sub>

Prefer

over

-- underscores in

some_variable_name

cause issues in some parsers.

Links and Images

[Text](https://example.com)                    # inline link
[With title](https://example.com "Hover")      # titled link
[Relative](./docs/setup.md)                    # relative path
[Anchor](#section-name)                        # heading link
![Alt text](./images/screenshot.png)           # image

<!-- Reference-style (cleaner in long docs) -->
See the [guide][contrib] and [CoC][coc].
[contrib]: ./CONTRIBUTING.md
[coc]: ./CODE_OF_CONDUCT.md

Lists

- Item one                    # unordered (use - consistently)
  - Nested (2-space indent)
1. First step                 # ordered
2. Second step
- [x] Done                   # task list (GFM)
- [ ] Pending

Code Blocks

Inline: `npm install`

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

```diff
- const port = 3000;
+ const port = process.env.PORT || 3000;
```

Always specify the language:

javascript

typescript

python

bash

json

yaml

sql

html

css

diff

Blockquotes and Rules

> Blockquote text.
> > Nested quote.

---                           # horizontal rule (blank lines above/below)

2. GitHub Flavored Markdown (GFM)

Tables

| Feature | Free | Pro    | Enterprise |
|---------|------|--------|------------|
| Users   | 5    | 50     | Unlimited  |
| Storage | 1 GB | 10 GB  | 100 GB     |

| Left       | Center     | Right      |
|:-----------|:----------:|------------|
| aligned    | centered   | right      |

Alerts (GitHub)

> [!NOTE]          > [!TIP]           > [!IMPORTANT]
> Info text.       > Advice text.     > Key info.

> [!WARNING]       > [!CAUTION]
> Urgent info.     > Negative consequences.

Footnotes

This needs a source[^1].
[^1]: Source: https://example.com/study

Autolinks and Mentions

https://example.com      <!-- auto-linked -->
@username                <!-- user mention -->
#123                     <!-- issue reference -->
org/repo#456             <!-- cross-repo reference -->

3. Advanced Patterns

Collapsible Sections

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

Content here (blank line required after summary tag).

</details>

Math / LaTeX

Inline: $E = mc^2$

$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
$$

Mermaid Diagrams

```mermaid
graph TD
    A[Request] --> B{Auth?}
    B -->|Yes| C[API Gateway]
    B -->|No| D[Login]
    C --> E[(Database)]
```

```mermaid
sequenceDiagram
    Client->>Server: POST /api/users
    Server->>DB: INSERT
    DB-->>Server: OK
    Server-->>Client: 201 Created
```

## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
  - [CLI](#cli)
  - [API](#api)

Anchor rules: lowercase, spaces become

, strip punctuation. Auto-generate with

scripts/markdown-linter.sh

(

generate_toc

function), VS Code "Markdown All in One", or

markdown-toc

npm package.

4. README Authoring

Badges (shields.io)

![Build](https://img.shields.io/github/actions/workflow/status/owner/repo/ci.yml?branch=main)
![Version](https://img.shields.io/npm/v/package-name)
![License](https://img.shields.io/badge/license-MIT-blue)
![Coverage](https://img.shields.io/codecov/c/github/owner/repo)
![Custom](https://img.shields.io/badge/docs-latest-brightgreen?logo=readthedocs)

Parameters:

?style=flat-square

?logo=typescript

?label=custom

?color=ff6600

README Template

See

examples/markdown-structure.json

for a structured template and

references/tech-writing-guide.md

for guidance. Standard sections in order:

Project Name + badges -- one-liner description with build/license/version badges
Features -- bullet list of key capabilities
Quick Start -- minimal install + usage code block
Installation -- detailed prerequisites and setup
Usage -- code examples, basic and advanced
Configuration -- table of options with types and defaults
Contributing -- link to CONTRIBUTING.md
License -- license type and link

Project Structure Trees

src/
├── index.ts          # Entry point
├── routes/
│   ├── auth.ts       # Auth routes
│   └── users.ts      # User CRUD
└── utils/
    └── logger.ts     # Logging

Generate with

tree -I node_modules

, then annotate.

5. Technical Documentation

Follow this hierarchy (detailed in

references/tech-writing-guide.md

Overview -- what and why
Prerequisites -- tools, versions, access
Installation -- step-by-step
Quick Start -- minimal working example
Detailed Guide -- full walkthrough
API Reference -- every public interface
Troubleshooting -- common errors and fixes
Changelog -- version history

API Endpoint Pattern

### Create User
`POST /api/v1/users`

| Field   | Type   | Required | Description       |
|---------|--------|----------|-------------------|
| `name`  | string | Yes      | Full name         |
| `email` | string | Yes      | Email address     |

**Response (201):**
\`\`\`json
{ "id": "usr_abc123", "name": "Alice", "email": "alice@example.com" }
\`\`\`

6. MDX

MDX combines markdown with JSX for interactive docs (Docusaurus, Nextra, Astro). MDX v2+ uses ESM imports.

import { Button } from '@/components/Button';
import { Callout } from '@/components/Callout';

# Button Component

<Callout type="info">Requires a parent `ThemeProvider`.</Callout>

<Button variant="primary">Click me</Button>

| Prop      | Type                        | Default     |
|-----------|-----------------------------|-------------|
| `variant` | `'primary' \| 'secondary'`  | `'primary'` |
| `size`    | `'sm' \| 'md' \| 'lg'`      | `'md'`      |

7. Markdown Linting

markdownlint

npm install -g markdownlint-cli
markdownlint "**/*.md"
markdownlint --fix "**/*.md"

Configuration (

.markdownlint.json

{
  "MD013": { "line_length": 120 },
  "MD033": false,
  "MD041": true,
  "MD024": { "siblings_only": true }
}

Key rules: MD001 heading increment, MD009 no trailing spaces, MD013 line length, MD024 no duplicate sibling headings, MD033 no inline HTML (disable for

<details>

<kbd>

), MD041 first line is H1.

remark-lint

npm install remark-cli remark-preset-lint-recommended
npx remark --frail docs/

CI Integration

Use

scripts/markdown-linter.sh

for local linting. For CI:

- name: Lint Markdown
  uses: DavidAnson/markdownlint-cli2-action@v19
  with:
    globs: '**/*.md'

Use

scripts/markdown-stats.py

to estimate reading time and word counts.

8. Conversion

pandoc README.md -o README.html              # basic HTML
pandoc README.md -s --toc -o README.html     # standalone with TOC
pandoc README.md -o README.pdf               # PDF (requires LaTeX)
npx marked -i README.md -o README.html       # GFM-compatible

9. Common Mistakes

Mistake	Fix
No blank line before list	Add blank line above
No blank line after heading	Always blank line after
Spaces in URL `[text](my url)`	URL-encode: `%20` or use `<url>`
Missing language on code fence	Always add: ```python
Mixing `*` and `-` for lists	Pick one, stick to it
Wrong nested list indent	2 spaces for unordered, 4 for ordered
`---` without blank line above	Becomes Setext heading -- add blank line
Bare URLs	Use `<https://url>` or `[text](url)`

Escaping

\*literal asterisks\*   \# not a heading   \| not a table pipe

Characters needing escape:

{}

[]

()

10. Editor Setup

VS Code: Markdown All in One (shortcuts, TOC, preview), markdownlint (inline warnings), Markdown Preview Mermaid Support, Paste Image.

Prettier: Add

"proseWrap": "always"

and

"printWidth": 80

in an override for

*.md

files.