Skip to content
Skills Library
Documents & office · Conversion & formats

markdown-syntax-formatter

/markdown-syntax-formatter

Converts text with visual formatting into proper Markdown syntax, fixes Markdown formatting issues, and ensures consistent document structure. Use this skill when formatting or reviewing Markdown files, fixing heading hierarchies, converting visual cues to proper syntax, applying Swiss German orthography to German-language documents, or checking Markdown against linting rules.

Licence
MIT
Last repository change
15.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Converts text with visual formatting into proper Markdown syntax, fixes Markdown formatting issues, and ensures consistent document structure. Use this skill when formatting or reviewing Markdown files, fixing heading hierarchies, converting visual cues to proper syntax, applying Swiss German orthography to German-language documents, or checking Markdown against linting rules.

Original author description

Converts text with visual formatting into proper Markdown syntax, fixes Markdown formatting issues, and ensures consistent document structure. Use this skill when formatting or reviewing Markdown files, fixing heading hierarchies, converting visual cues to proper syntax, applying Swiss German orthography to German-language documents, or checking Markdown against linting rules.

How it works

  1. Capabilities
  2. Workflow
  3. Output Standards
  4. Heading Rules
  5. List Rules
  6. Code Block Rules
  7. Emphasis Rules
  8. Language-Specific Handling
  9. Linter Exceptions
  10. Examples
Original SKILL.md headings · 193 lines, 836 words
SKILL.md preview
---
name: markdown-syntax-formatter
description: >
  Converts text with visual formatting into proper Markdown syntax, fixes Markdown
  formatting issues, and ensures consistent document structure. Use this skill when
  formatting or reviewing Markdown files, fixing heading hierarchies, converting
  visual cues to proper syntax, applying Swiss German orthography to German-language
  documents, or checking Markdown against linting rules.
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
  - Glob
---

# Markdown Syntax Formatter

Format and repair Markdown documents following CommonMark and GitHub Flavored Markdown
specifications. Ensure proper syntax, consistent structure, and correct rendering across
standard parsers.

## Capabilities

- Analyze document structure to identify intended hierarchy and formatting elements
- Convert visual formatting cues (ALL CAPS, bullet characters, emphasis indicators) into
  proper Markdown syntax
- Fix heading hierarchies ensuring logical progression without skipped levels
- Format lists with consistent markers and proper indentation
- Handle code blocks and inline code with appropriate language identifiers
- Apply Swiss German orthography rules to German-language content
- Respect context-specific linter exceptions (e.g., duplicate headings in training
  materials)

## Workflow

1. **Analyze** the input text to identify headings, lists, code sections, emphasis, and
   structural elements
2. **Transform** visual cues into correct Markdown syntax
3. **Ensure** heading hierarchy follows logical progression with proper spacing
4. **Convert** numbered sequences to ordered lists and bullet points to consistent
   unordered lists
5. **Apply** proper code block formatting with language identifiers where recognizable
6. **Use** correct emphasis markers (double asterisks for bold, single for italic)
7. **Apply** language-specific conventions when the document is in German (see
   [Swiss German Conventions](swiss-german-conventions.md))
8. **Verify** that all syntax renders correctly and follows Markdown best practices

## Output Standards

- Clean, well-formatted Markdown that renders correctly in standard parsers
- Proper document structure with preserved logical flow
- Consistent formatting for lists, headings, code blocks, and emphasis
- Correct spacing and line breaks following Markdown conventions
- Quality-checked output without broken formatting or parsing errors
- Context-aware formatting decisions for ambiguous cases based on common conventions

## Heading Rules

- Never skip heading levels (e.g., do not jump from `##` to `####`)
- Ensure a single `#` top-level heading per document
- Add a blank line before and after each heading
- Use ATX-style headings (`#`) consistently, not Setext-style (underlines)

## List Rules

- Use `-` for unordered lists (consistent marker)
- Use `1.` for all ordered list items (let the renderer handle numbering)
- Indent nested lists by 2 or 4 spaces consistently within a document
- Add a blank line before and after list blocks

## Code Block Rules

- Use fenced code blocks (triple backticks) with a language identifier
- Use inline code (single backticks) for short code references in prose
- Never nest code blocks
- Ensure closing fence matches opening fence

## Emphasis Rules

- Use `**bold**` for strong emphasis
- Use `*italic*` for regular emphasis
- Do not use underscores for emphasis in filenames or mixed contexts
- Avoid combining bold and italic unless semantically justified

## Language-Specific Handling

When the document contains German text, apply Swiss German orthography rules
automatically. See [Swiss German Conventions](swiss-german-conventions.md) for the
complete ruleset including:

- Replacing ß with `ss` in all German text
- Preserving proper umlauts (no digraph substitutions)
- Exceptions for code blocks, URLs, and external quotations

## Linter Exceptions

Certain Markdown linting rules have legitimate exceptions depending on document context.
See [Linter Exceptions](linter-exceptions.md) for detailed guidance on:

- MD024 (duplicate headings) in training materials, API docs, and templates
- Respecting project-level `.markdownlint.json` configuration
- When to suggest alternatives vs. when to accept exceptions

## Examples

### Fixing Heading Hierarchy

**Before:**
```markdown
# Title
### Subsection (skipped h2)
##### Detail (skipped h3, h4)
```

**After:**
```markdown
# Title

## Subsection

### Detail
```

### Converting Visual Formatting

**Before:**
```
INTRODUCTION

This is the main text. The IMPORTANT POINTS are:
* first item
* second item
  - sub item a
  - sub item b
* third item

NOTE: Pay attention to this.
```

**After:**
```markdown
## Introduction

This is the main text. The **important points** are:

- First item
- Second item
  - Sub item a
  - Sub item b
- Third item

> **Note:** Pay attention to this.
```

### Code Block Formatting

**Before:**
```
Here is some code:

    function hello() {
        console.log("hello");
    }
```

**After:**
````markdown
Here is some code:

```javascript
function hello() {
    console.log("hello");
}
```
````

## Troubleshooting

### Mixed-Language Documents

Documents containing both German and English text require careful handling:

- Apply Swiss German orthography only to German-language sections
- Leave English sections unchanged
- When language boundaries are unclear, ask the user which sections are German
- Code blocks and technical terms remain unchanged regardless of surrounding language

### Conflicting Linter Configuration

When a project's `.markdownlint.json` conflicts with this skill's formatting rules:

- Project configuration takes precedence over skill defaults
- Read the configuration file before applying formatting changes
- If a rule is disabled in project config, do not "fix" what the linter allows
- Document any deviation from standard formatting in a comment to the user

### Large Documents with Many Issues

When a document has extensive formatting problems:

- Fix structural issues first (heading hierarchy, document outline)
- Then address list formatting and consistency
- Apply code block formatting next
- Handle emphasis and inline formatting last
- Apply language conventions (Swiss German) as a final pass
- Present a summary of changes made to the user
Files in this package (3)
  • SKILL.md 6 KB
  • linter-exceptions.md 3 KB
  • swiss-german-conventions.md 3 KB

Versions

The database has no other skills named markdown-syntax-formatter.

Database snapshot: 13.11.2026 · package version f1353467ccca (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100google-chat-formatting
    Convert Markdown to Google Chat formatting. Use when formatting messages for Google Chat or converting Markdown documents to Google Chat syntax.
  • 100markdown-syntax-fundamentals
    Use when writing or editing markdown files. Covers headings, text formatting, lists, links, images, code blocks, and blockquotes.
  • 95flowmark
    Fast, consistent Markdown auto-formatter for typographic cleanup, normalization, and clean semantic line breaks. Use when creating, editing, or cleaning Markdown; formatting LLM-generated docs; adopting Flowmark in a repository; adding Markdown format scripts or commit hooks; or…
  • 100markdown-formatting
    Use when writing PR descriptions, issue bodies, documentation, or notes - applies consistent Markdown conventions (heading levels, list markers, code-block languages, link text) and provides PR and issue templates
  • 100obsidian-markdown-structure
    Validate and enforce markdown document structure including frontmatter positioning, heading hierarchy, and content organization. Use when creating or validating markdown files.
  • 100markdown-conventions
    Markdown formatting conventions covering heading hierarchy, code blocks, tables, lists, links, images, and accessibility best practices. Apply this skill whenever writing or editing .md files -- including READMEs, documentation pages, changelogs, or any markdown content -- even…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.