yf-markdown-format

The autofix side of `yf-markdown-lint` — rewrites Markdown in place to conform to plain GFM along the axes the linter flags. Owns two transforms: strict GFM table alignment (`--check` gate / `--write` idempotent autofix / bare stdout) and Obsidian to GFM wiki-link migration.

At a glance

• Category: markdown
• Invocation: auto (fires from its description conditions when relevant work appears)
• Requires tools: uv
• Source: SKILL.md · README.md

When it fires

/yf-markdown-format invoked; aligning GFM tables; converting `[[wiki-links]]` to GFM links; a write-in-place markdown fix.

When to skip it

validating markdown (use `yf-markdown-lint`); rendering to PDF/HTML (use `yf-markdown-pdf` / `yf-markdown-html`). OPT-IN per repo — never an always-on autofix.

Prerequisites

Mirrors SKILL.md frontmatter depends-on-tool: [uv]. No init step, no config, no companion rule.

Usage

User-invocable. Two independent transforms.

Table alignment (scripts/md_table_align.py) — --check gate, --write idempotent in-place autofix, or bare stdout:

# CI / pre-commit gate: exit 1 if any table would change, mutating nothing
uv run .claude/skills/markdown-format/scripts/md_table_align.py --check PATH...
# idempotent in-place autofix (running twice is a no-op)
uv run .claude/skills/markdown-format/scripts/md_table_align.py --write PATH...
# normalized document to stdout
uv run .claude/skills/markdown-format/scripts/md_table_align.py PATH...

--check reports at file granularity (no per-table line number): it lists the offending files and exits 1, or prints all tables strictly aligned and exits 0.

Wiki-link migration (scripts/convert_wikilinks.py) — Obsidian [[…]] / ![[…]] to GFM links/images; dry-run or in-place; always exits 0:

# dry-run: report the rewrites it WOULD make, touching no files
uv run .claude/skills/markdown-format/scripts/convert_wikilinks.py <dir>... --vault-root DIR --dry-run
# in-place migration + a full conversion report
uv run .claude/skills/markdown-format/scripts/convert_wikilinks.py <dir>... --vault-root DIR --report report.md

Both scripts are documented in SKILL.md: the three alignment modes, East-Asian-width awareness, fenced-code skip, and the code-aware, best-effort-resolving, idempotent wiki-link migration.

Migrating from a vendored copy

Some downstream repos (dixson3/obsidian-primary, dixson3/d3-pxe) currently vendor their own scripts/md_table_align.py — a per-repo copy. Now that this skill ships the canonical md_table_align.py (byte-identical origin), those repos can:

• delete the vendored scripts/md_table_align.py copy (and any convert_wikilinks.py reference), and
• point their AGENTS.md at this skill instead of the local copy.

This is a downstream consequence recorded here as guidance — this repo does not execute any change in those other repos. Migrate each consumer on its own schedule.

Phase model

None. This is a tool/reference skill with no phases or state transitions.