# Rendered Markdown

> Use when Markdown must render: never hard-wrap issue-body paragraphs; fix GitHub code fences, fold logs into details, and pin source links to tags.

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

---


# Rendered markdown

Write the body so it renders, and link it so it still resolves in
three years.

Two references carry the rules, and they are the same ones
`/gh:create-issue` follows:

- `../../references/rendered-markdown.md` — wrapping,
  symbols, code fences, `<details>`, structure, and what to leave out.
- `../../references/source-links.md` — pinning,
  autolinking, cross-repo references, and the project link set.

## The test

Will a maintainer three years from now find this helpful? They will
not have the conversation, the open tab, or the branch. What survives
is the text and what it links to.

For a pull request that test also picks the subject: the branch's net
change, not the route it took.

## Core moves

- **Know which surface you are on.** GitHub renders a single newline
  as a line break in issue, pull request, and comment bodies, and as a
  space in a markdown file. So a comment body is never hard-wrapped,
  and a repository file follows the repository's own convention. Do
  not re-wrap a file to match a body.
- **Backtick every symbol** — functions, flags, paths, env vars,
  packages, types, verbatim errors. In the title too. Backticks are
  also how you stop `#123` or `@name` from linking.
- **Strip local paths and PII** before publishing: absolute home
  paths, hostnames, emails, tokens, internal URLs. Pasted logs are
  where they hide.
- **Fence liberally, one command per block**, no comments inside the
  fence, language tagged. A long command may wrap with `\`.
- **Fold long output into `<details>`** with a blank line after
  `</summary>` — without it the whole block renders as raw HTML.
- **Nested sections, not tables.** Rendered tables scroll sideways
  instead of reflowing and hide their right-hand columns.
- **Link at every opportunity, and pin what you link.** A release tag
  first, else a 7-character commit reachable from trunk, never
  `blob/main`. Name an open-source project once with its whole set:
  repository, homepage, docs, the changelog at that release, and its
  registry page.
- **Use the autolinks that already exist.** Bare `#123` and a bare
  7-character ref inside a GitHub body; `[REPO#123](url)` across
  repositories; a bare tracker key only when that repository actually
  resolves it.

## Calibrate to the project

Read `./AGENTS.md` and `./CLAUDE.md`. Where they define a house voice,
a slop rubric, or a wrap convention, that governs.

## Verify before publishing

Render the draft through GitHub's own renderer and read the output —
literal `**` means a `<details>` block lost its blank line, and a
`<br>` inside prose means the body is hard-wrapped.

```
gh api --method POST /markdown -f mode=gfm -f context=OWNER/REPO -f text="$(cat body.md)"
```

## Common mistakes

**Hard-wrapping an issue body at 72 columns.** Correct for a commit
message, correct for most repository files, wrong here — every newline
becomes a line break and the paragraph renders as ragged stubs.

**A `<details>` block with no blank line after `</summary>`.** The
fences, lists, and bold inside it all render as literal text. It is
the most common way a body ships broken.

**An alert inside `<details>` or a list item.** `> [!WARNING]`
degrades silently to a plain blockquote showing the marker.

**Linking `blob/main/…` with a line anchor.** It resolves forever and
points at different code every week.

**A table of contents linking to the body's own headings.** Issue-body
headings get no anchor ids; every one of those links is dead.

**@mentions as attribution.** They send mail. Name someone only when
you are asking them for something.

**Reformatting the repository to match.** This skill governs what you
are writing, not the files around it.