Argdown

argdown

Argdown is a Markdown-flavored DSL for argument maps. Source is a .argdown text file; the argdown CLI parses it, reports syntax errors with location info, and exports to SVG/DOT/HTML/JSON.

When this skill fires

• User asks to draft, edit, or lint a .argdown file
• User wants to structure a debate / pro-con / objection tree / premise-conclusion argument and visualize it
• User explicitly invokes $argdown or mentions "argument map", "argdown map", "claim/objection diagram"

Prerequisite

argdown CLI must be on PATH (/opt/homebrew/bin/argdown on this machine). Check with command -v argdown. If missing: npm install -g @argdown/cli. For SVG/PNG export, Graphviz is also needed: brew install graphviz.

Core workflow

1. Draft the .argdown file. Minimal skeleton:

   ===
   title: <topic>
   ===
   
   # <Section>
   
   [Main claim]: One-sentence thesis.
     + <Supporting Arg>: Why the thesis holds.
     - <Counter Arg>: Why it might not.
   
   <Supporting Arg>
   
   (1) Premise.
   (2) Premise.
   -----
   (3) [Main claim]
   

2. Lint — there is no separate lint subcommand. The default invocation parses and logs syntax errors with line/col:

   argdown path/to/file.argdown
   

   Or use scripts/lint.sh <file> (bundled): adds --throwExceptions so exit code is non-zero on parser errors — suitable for an iterate-until-clean loop.

3. Fix the reported errors. See "Gotchas" below for common ones.

4. Render once clean:

   argdown map path/to/file.argdown ./svg -f svg
   

   Or scripts/render.sh <file> [outdir] — wraps lint + map and prints the SVG path.

5. Iterate if the map looks wrong — adjust statements, relations, or --rankdir/label-mode flags.

Syntax cheat sheet

Full reference in references/syntax.md — load it when authoring a construct not covered here.

What the linter catches vs tolerates

Argdown's parser is permissive — it recovers from many surface errors and renders something. lint.sh (via --throwExceptions) fails reliably only on a narrow set of hard parse errors. The rest must be caught by visually checking the rendered SVG.

Hard errors lint.sh will fail on:

• Malformed PCS: missing ----- inference line, broken inference-detail block (-- / --), parser unable to reduce to a valid pcs rule.
• Unclosed inline formatting that spans into the next block. Most common offender: an underscore in an identifier (redact_long.go, chat_session_id) opens an italic span, the parser keeps reading expecting a closing _, and chokes when it hits a blank line or unexpected token. Error message names statementContent > italic in the rule stack.

Silent / tolerated (renders despite looking broken):

• Mismatched brackets like [Claim> — lexed as best-effort text.
• Non-consecutive PCS numbering ((1), (3), (5)) — argdown re-numbers internally.
• Pure gibberish lines — parsed as statements.
• @[Title] mentions to titles that were never defined — warning at most.
• Relation symbols at the wrong indent — silently re-interpreted as top-level.

Implication: after the lint passes, always render and skim the SVG before declaring the file correct.

Inline-formatting footguns

The body of a statement or argument description is parsed for markdown-style inline formatting before the rest of the rules apply. That means:

When in doubt, write descriptions as plain prose and put code-like tokens in `backticks` — argdown treats them as inline code and leaves them alone.

Citing sources with YAML metadata

Any statement definition or reference can carry YAML metadata. Use this to attach a citation to a claim so the rendered map can hyperlink or label by source.

Recommended schema for a citation, fields in priority order:

Inline form — use when the metadata fits on one line:

[Climate trend]: Global mean surface temperature rose 1.2 °C since 1850. {source: 10.1126/science.abc1234, author: Smith et al., date: 2023, title: HadCRUT5 reanalysis}

Block form — opening { followed by a newline activates YAML block mode; the brackets are ignored and the body between them is parsed as YAML:

[Climate trend]: Global mean surface temperature rose 1.2 °C since 1850.
{
  source: 10.1126/science.abc1234
  author: Smith et al.
  date: 2023-04
  title: A reanalysis of HadCRUT5
}

For URL sources, quote the value so the colons don't confuse the YAML parser:

[IPCC AR6]: Anthropogenic warming is the dominant cause of observed warming since 1850.
{
  source: "https://www.ipcc.ch/report/ar6/wg1/"
  author: IPCC
  date: 2021
  title: AR6 Working Group I Summary
}

Same metadata schema works for <Argument> definitions — drop the YAML block right after the argument title or description.

Useful CLI flags

• argdown -v <file> — verbose; shows the full AST.
• argdown map -f svg <in> <outdir> — SVG via Graphviz.
• argdown map -f dot <in> <outdir> — DOT only (no Graphviz needed).
• argdown map --argument-labels title --statement-labels text — compact arg labels, full statement text.
• argdown map --rankdir LR — left-to-right layout.
• argdown html <in> <outdir> — standalone HTML with interactive map web-component.
• argdown json <in> <outdir> — full parsed model as JSON for downstream tooling.
• argdown --watch — re-run on file change.

Bundled scripts

• scripts/lint.sh <file> — fail-fast lint (exit 1 on parser error). Use this in the iterate loop.
• scripts/render.sh <file> [outdir] — lint then render to SVG; prints output path.

Both scripts assume argdown is on PATH.

Reference

• references/syntax.md — full Argdown syntax reference from argdown.org. Load when authoring a construct not covered above.