Markdown Style

Use when writing or editing Markdown documentation (*.md files). Covers GFM formatting, content structure, headings, lists, code blocks, links, images, tables, and front matter.

hugobatista Updated

File contents

Content Rules

  • Headings: H2/H3 only — no H1 (auto-generated). Hierarchical order; recommend restructuring at H4+
  • H1 emoji: When writing a project README (where H1 is the title), append a descriptive emoji icon after the title text — e.g. # Project Name 🚀
  • Lists: - for bullets, 1. for numbered. Two-space indent for nesting
  • Code blocks: Fenced with triple backticks; always specify language
  • Links: [text](URL) — descriptive text, valid URL
  • Images: ![alt text](URL) — always include alt text
  • Tables: |-delimited with aligned headers
  • Line length: Max 400 chars; soft-break long paragraphs at ~80 chars
  • Whitespace: Blank lines between sections; no excessive whitespace

Front Matter

When front matter is required, include relevant metadata fields. Common fields:

title:
description:
author: hugobatista
date:
tags:

Validation

Run validation tools to verify front matter completeness, content rules, and formatting compliance.

hugobatista/agent-skills/tree/main/skills/docs/markdown-style commit a80f9e7687

Frequently asked questions

npx skillmds@latest add hugobatista/markdown-style