---
name: markdown-docs-formatter
description: "Turns rough notes into a publication-ready Markdown document with clean headings, lists, tagged code blocks, and tables, pitched at the reader level you choose. Use when rough notes or a dump of text need turning into clean Markdown with proper headings, lists, code fences, and tables before publishing. Do not use for writing new content from an outline, or checking a finished file for broken links. Related topics: coding, markdown."
---

# Markdown Docs Formatter

Turns rough notes into a publication-ready Markdown document with clean headings, lists, tagged code blocks, and tables, pitched at the reader level you choose.

## When to use

Use this skill when rough notes or a dump of text need turning into clean Markdown with proper headings, lists, code fences, and tables before publishing. Do not use it for writing new content from an outline, or checking a finished file for broken links.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Inventory every fact, command, and code fragment in the notes so nothing is lost in the reshape.
3. Assign H2 to each section and H3 where a section changes topic, keeping the original order.
4. Convert lists, procedures, and parallel facts into bullets, numbered steps, and tables respectively.
5. Fence every code fragment with its language tag and place images per the placement setting with alt text.
6. Generate the table of contents from the final headings when enabled and return the file as one markdown fence.

## Inputs

- **Document title** (free text, e.g. "Title of the document")
- **Audience level** (choose one: Beginner, Intermediate, Advanced)
- **Include table of contents** (choose one: Yes, No)
- **Sections** (longer free text)
- **Code language preference** (choose any: Python, JavaScript, Bash, SQL, None)
- **Image placement** (choose one: Top, Bottom, Inline)

## Output

A single fenced code block tagged markdown holding the formatted document: H1 title, optional table of contents, then H2 sections with H3 subsections, lists, tables, and tagged code fences.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Markdown Docs Formatter

Format my raw notes into a polished Markdown document.

- Document title: {{Document title}}
- Audience level: {{Audience level}}
- Include table of contents: {{Include table of contents}}
- Sections: {{Sections}}
- Code language preference: {{Code language preference}}
- Image placement: {{Image placement}}

Keep every fact and every code line from the notes; reshape, do not rewrite. Promote each section name to an H2 and split a long section into H3 subsections where the notes change topic. Turn comma-separated lists into bullet lists, ordered procedures into numbered lists, and any set of parallel facts (option and meaning, flag and effect) into a table. Fence every code fragment with the matching language tag from the preference list, and leave a fragment inline in a code span when it is a single identifier. Pitch the connective text at the audience level: spell out terms for beginners, keep it terse for advanced readers. Place image references where the placement option says, with alt text drawn from the note next to them. When the table of contents is on, generate it from the final H2 headings with matching anchors. Return the formatted document as a fenced code block tagged markdown and nothing else.

## Pitfalls

- Paraphrasing the notes while formatting, which quietly changes technical meaning.
- Guessing a language tag for a code fragment, which breaks syntax highlighting and misleads readers.
- Turning a three-item list into a table, which adds visual weight without adding clarity.
