markdown-authoring
Markdown style patterns to use when writing documents.
When & Why to Use This Skill
This Claude skill provides a comprehensive set of Markdown styling patterns and rules designed to ensure consistency, readability, and professional structure in document authoring. It automates and enforces formatting standards such as ATX heading styles, specific list indentation, semantic line breaks, and automatic Table of Contents (TOC) generation, making it an essential tool for maintaining high-quality documentation.
Use Cases
- Technical Documentation: Standardizing the structure and style of software manuals, README files, and API documentation to ensure a uniform professional appearance.
- Collaborative Writing: Enforcing 'Semantic Line Breaks' and consistent spacing to make version control (Git) diffs cleaner and more manageable for teams.
- Automated Navigation: Automatically generating and updating a Table of Contents for long-form documents with more than four sections to improve user navigation.
- Content Refactoring: Quickly reformatting inconsistent or legacy Markdown files to comply with modern web standards and organizational style guides.
| name | markdown-authoring |
|---|---|
| description | Markdown style patterns to use when writing documents. |
When writing Markdown files:
Start with an H1 as the first heading. The first heading in the file should be a top-level
# Heading(not##or deeper).Use ATX headings only. Headings must use leading
#characters (#,##,###, …), not Setext (Heading+====).Unordered list marker is flexible. You may use
-,*, or+for bullet lists (no enforcement).Indent nested unordered lists by 2 spaces. When a list item contains a nested list, indent the nested list by 2 spaces.
Blank lines are allowed more freely. Extra consecutive blank lines are permitted (no “single blank line only” restriction).
Line length limit is effectively very high; but follow sembr For prose, follow the Semantic Line Breaks convention, described in
<path-to-skill>/reference/sembr.md. Table rows are not checked for line length.Headings must be surrounded by blank lines. Put a blank line before and after each heading (where applicable).
Duplicate headings are allowed. Reusing the same heading text in multiple places is acceptable.
Lists must be surrounded by blank lines. Put a blank line before a list and a blank line after a list.
Inline HTML is allowed. HTML (like
<br>,<details>, etc.) is permitted in Markdown.Add Table of Contents. If there are more than 4 sections, add a table of contents by adding this (if not already present):
## Contents
<!-- toc -->
<!-- tocstop -->
- Run command
just -g toc [path-to-file.md]when complete. The just recipe is configured with[no-cd], somarkdown-tocwill run from the working directory you call the just command with.