markdown-authoring

---

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

Copy
## 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.