# Markdown Authoring

> Markdown style patterns to use when writing documents.

- Skill: `majiayu000/markdown-authoring` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/markdown-authoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/markdown-authoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/markdown-authoring

---


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):

```markdown

## Contents

<!-- toc -->
<!-- tocstop -->

```

- Run command `just -g toc [path-to-file.md]` when complete. The just recipe is configured with `[no-cd]`, so `markdown-toc` will run from the working directory you call the just command with.