Argdown gives argument maps a plain-text syntax inside Markdown

An argument map that starts as a list of pros and cons

Argument mapping software tends to arrive with a cost: a canvas, a mouse, a node per claim, and a file format only the tool understands. Argdown takes the opposite position. It is described as a simple syntax for analysing complex argumentation, and the entry point is deliberately low: listing pros and cons is as simple as writing a twitter message, and you do not have to learn anything new except a few simple rules that are meant to feel natural.

From that base you can define more complex relations between arguments, and you can dig into the logical premise and conclusion structures behind them. The progression matters for the audience. A team that wants a record of a decision can start with a list of arguments for and against, and if the discussion becomes contested, the same text can carry a structured map of how premises support conclusions. Nothing has to be migrated into a different tool because the map was always the source text.

The second capability that makes Argdown different is that the syntax works inside Markdown. The overview states that Argdown can be used within Markdown and that your code is transformed into an argument map while you are typing. So the file is a Markdown document, readable in any editor, with the argument structure embedded in it rather than stored beside it. That property is what makes version control, diffing and code review work on argument maps.

The audience is people who think in arguments: researchers, policy analysts, debate teams, and anyone who has to defend a position in writing. The tools shipped around the syntax, a playground, a VS Code extension, web components and image export, all serve that workflow of writing and publishing an analysis rather than drawing a picture.

The monorepo holds a dozen packages, not one tool

The repository is a monorepo containing all packages of the Argdown project, with internal dependencies managed through yarn workspaces and every package living in the packages/ folder. The root package.json confirms it is private and declares the workspaces pattern packages/**/*, and the package manager is pinned to yarn 4.9.4 with a Node engine constraint of >= 20.0.0.

The lint script in the root package.json is an accidental index of the whole project, because it names every package directory explicitly: argdown-cli, argdown-core, argdown-image-export, argdown-language-server, argdown-map-views, argdown-node, argdown-vscode, argdown-web-components, two Markdown plugins under markdown-plugins, one of them argdown-markdown-it-plugin and the other argdown-marked-plugin, and a sandbox package used for the browser playground.

That list describes the architecture better than any summary could. argdown-core holds the parser and the model. argdown-node and argdown-cli are the two programmatic entry points, one as a library and one as a command line tool. argdown-map-views and argdown-web-components turn the parsed model into something you can see, either in a page or as a component you embed. argdown-image-export produces a picture, which is the path to the PDF and image outputs the overview mentions. argdown-language-server and argdown-vscode are the editor integration, and the two Markdown plugins mean the syntax can be rendered by markdown-it or by marked, which is how the live transformation while typing works.

Around that sit the usual monorepo machinery: lerna drives the per-package build and test scripts, nx is used to draw the dependency graph through the graph script, changesets handles versioning, and prettier and eslint are configured at the root with a lint script and a separate lint:all that covers every package plus the sandbox.

Building the monorepo and running the docs site locally

There is no single published CLI in the overview, so the install path it documents is a source build of the monorepo. The steps it lists are: clone the repository and change into the project directory, install the requirements, run yarn install in the main folder, run yarn build, run yarn test for the tests, and run yarn workspace @argdown/docs run dev to deploy the docs website locally.

The requirements are stated as node>=22.11.0, for example via nvm, and yarn>=4.9.4, via corepack. Note that the root package.json declares a weaker engine constraint of node >= 20.0.0, so the README asks for a newer Node than the manifest enforces. If you hit an install or build failure on Node 20, this discrepancy is the first thing to check.

The build and test steps are thin wrappers around the package manager, and the root package.json shows what they do:

"build": "lerna run build",
"test": "lerna run test",
"graph": "nx graph"

So a build is a build in every package, a test run is a test run in every package, and the graph script opens the nx dependency view of the workspace, which is the tool you want when you are trying to understand which package depends on which. The commands themselves are:

yarn install
yarn build
yarn test
yarn workspace @argdown/docs run dev

For a user who just wants to see the syntax rather than work on the code, the project points at a browser sandbox, and for a user who wants to write in an editor there is a VS Code extension with an installation page. The playground and the extension are the low friction entry points, and the monorepo build is what you need only when you intend to change the tool itself.

From text to map, component, image or PDF

The output targets in the overview are diverse, and each one corresponds to a different publishing need. The argument map is the core rendering, a live view of how arguments relate, which is what the web components package serves. The PDF and the web component embed are the two sharing paths: one for a document, one for a page that already exists. Exporting the map as an image is the third, and it is the fastest route into a slide deck, a wiki page or a chat message.

Each path has a different constraint on the author. A PDF implies a fixed layout and a print or document reader. A web component means your page loads a component and hands it the Argdown source, so the reader's browser does the rendering. An image is a terminal format: it cannot be re-rendered, so if the analysis changes, the picture is stale. The image export package in the monorepo exists precisely because that last case is common enough to need a dedicated tool.

The editor integration deserves a note as well. A language server package next to a VS Code extension package means the syntax support is not a text-mode hack, it is a proper language implementation with the editor asking for diagnostics, completions and previews. When the same core package backs the CLI, the node library, the editor and the browser sandbox, a change to the grammar shows up in all of them, which is the payoff of the monorepo layout and also the reason a breaking grammar change is a breaking change everywhere.

The examples folder is the specification in practice

Argdown's distribution of documentation is unusual, and the repository makes it visible. The examples/ directory holds ready made files, including an argument primer, a populism core argument example, a state censorship example, a legalisation of soft drugs example, a semmelweis example and a greenspan and schefczyk hardwrap example. The screenshots referenced in the overview line up with some of these, showing the same source rendered in the VS Code extension and in the browser sandbox.

For a new user this is the fastest route into the syntax. Reading a file that someone else wrote, and seeing how it renders, teaches the rules faster than a grammar reference, and the argument primer is the one to open first if you want the introduction. The examples also serve as fixtures: they are concrete, non trivial argument structures that a tool change can be checked against, which is a good property for a project whose output is a picture people argue over.

The repository also carries a few files that suggest a wider audience than the code. There is a context7.json at the root and an llms.txt, which are conventions for serving documentation context to language model tooling, and there is a DEVELOPMENT.md alongside the README for contributors. The .changeset/ directory holds the versioning change entries, and the presence of a .prettierrc and eslint.config.mjs shows that formatting and linting are enforced at the repository level rather than left to the individual package.

Licensing, funding and a repository without releases

The licence situation has a wrinkle worth checking before you build on it. The README states that all code is published under the MIT licence, and the root package.json carries the same MIT designation. The licence field on the GitHub page is listed as unknown, so the README and the manifest are the sources to read, and the optional Argvu font is published separately under a Free License. Nothing in the overview suggests a commercial restriction, but a fork or a redistribution should start by reading the LICENSE file in the repository rather than the badge.

Funding is stated plainly: the development of Argdown and Argdown related tools is funded by DebateLab at KIT, Karlsruhe. That is a research group at a technical university, and it explains the shape of the project, a language and its tooling built for argument analysis research with a public documentation site and a sandbox for experimentation.

The maintenance picture is mixed, and it is the reason to look before committing. The repository is not archived, and the last push was on 2026-09-10, so work is still landing. But the repository has no GitHub releases at all, which means there is no tagged version history to pin against, and the versioning happens per package through the changesets workflow rather than through tags you can see at the repository level. A team that wants a fixed version of a package has to look inside the packages directory rather than at the repository's release list. Combined with a monorepo where a grammar change propagates to the CLI, the editor and the web components at once, that is the operational shape you should plan for: follow the packages you depend on, and expect to read the change notes before upgrading.

Editorial conclusion

Argdown suits analysts, researchers and debate teams who want an argument map that stays in version control as text and can be read without any tooling, and it suits teams willing to build the monorepo rather than install a single tool. It is the wrong choice if you need a packaged command line binary ready to install, because the overview documents a monorepo you clone and build yourself, and it is a poor match if you want to store arguments in a structured database, since the source of truth here is a Markdown file. Before adopting, check the licence field on the GitHub page, which is listed as unknown while the README and the root package.json both state MIT, and confirm your Node version satisfies both the engine constraint in package.json and the version the README asks for.

Frequently asked questions

Official sources

1. argdown/argdown on GitHub
2. Issues
3. Project website
4. README