Argdown is great for representing argumentation structures. But what if you want to do more than represent the structure?

When analysing an argumentative text, you may want to document interpretational decisions, preserve alternative reconstructions, quote and reference the source text, and add notes explaining your analysis. And when presenting the analysis to others, you may want to combine argument maps with prose, argument reconstructions, quotations, and a larger narrative.

This is where Markdown and Quarto come in. In this post, I show how Markdown documents containing Argdown source blocks can be used to document and present argumentation analyses, and introduce a template for turning them into polished PDFs with Quarto.

Argdown is a simple syntax used to describe arguments, their internal premise-conclusion structure and argumentative support and attack relations between arguments. Since Argdown is machine-readable, Argdown documents can easily be used to automatically generate argument maps, visualising the relationships between arguments as a graph.

Argdown Snippet 1 depicts a small Argdown snippet that describes a schematic macrostructure of four arguments. By clicking on the “map” button, you can see the argument map generated from this Argdown snippet.

[Main claim]: Main claim, justified or criticised by arguments. #pro
    + <1. Argument>: Argument supporting the main claim. #pro
    + <2. Argument>: Another argument supporting the main claim. #pro
    - <3. Argument (objection)>: Argument formulating an objection 
    to the main claim. #con
        - <4. Argument (rebuttal)>: Argument rebutting the objection. #pro

In this way, Argdown files can represent both the internal structure of individual arguments and the argumentative relations between them.

However, the mere argumentation structure is often only one piece within the larger context of how that structure serves a specific end. Two very important and connected use cases are the following:

1. Process of argumentation analysis: Suppose you want to understand the argumentation in an argumentative text better. Using tools from logic and argumentation theory, you reconstruct the arguments you identified in the text in their premise-conclusion structure and analyse their relationships. Argumentation analysis is rarely a matter of simply identifying a fixed structure that is already apparent in the text. It is an interpretative process that often involves competing reconstructions, revision cycles, and decisions that are not self-explanatory. Accordingly, it is advisable to document your analysis in a way that is easy to share with others and that allows you to update your analysis as you revise your understanding of the text. To that end, you should explain your interpretational decisions, take notes about alternative interpretations, document references to the text, provide textual evidence and so on.
2. Presenting analyses of argumentation: Suppose you want to present your analysis of an argumentative text to others, for instance, to share your insights or to support your own claims based on your analysis. Simply providing the audience with the result of your analysis, that is, the resulting argumentation structure (either as an Argdown file or as an argument map), is usually not enough. While an argument map shows the argumentation structure, it does not necessarily explain why the analysis takes this form. You want to present your analysis in a way that is easy to understand, and that allows the audience to follow your reasoning. This usually requires a combination of text, argument reconstructions and argument maps. For instance, you might want to add explanatory comments on specific arguments by, for instance, explaining the relevance of a specific premise, or you might want to add a summary of some arguments and their role, or you might even want to embed the analysed argumentation in a larger narrative.

In both cases, the mere argumentation structure is only one of many pieces. You need to complement the structural information with additional, often unstructured information.

There are several ways to organise this additional context information. For instance, you could create separate documents that contain this additional information and add references to your argumentation analysis. Or you can add this information directly to the Argdown file as comments, or by using Markdown syntax in the Argdown file, or even as YAML data.

These options are useful especially for the first use case. However, it can get a little bit cumbersome if the context information is extensive. For the second use case, however, these options are usually not very suitable. In particular, Argdown files are not designed for the purpose of creating polished documents that combine text, argument reconstructions and argument maps. A much more promising approach is to use Markdown documents that include Argdown source blocks. In this way, you can combine the advantages of Argdown files for argumentation analysis with the advantages of Markdown documents:

• Centralised narrative context: combine argument reconstructions with prose explanations, quotations, notes, and references in one single file.
• Versioning and sharing: keep the analysis and its documentation in a plain-text file that can be easily shared and versioned (e.g., via git).
• Editor independence: use any Markdown editor of your choice to write and edit the document.
• Separation of content and presentation: write the analysis in Markdown syntax while leaving typography and PDF layout to rendering tools (e.g., Quarto/Pandoc).

The last point is particularly important for the second use case. While Argdown files can be rendered to HTML documents and argument maps, they are not very suitable for creating polished PDF documents. In this post, I will focus on using Quarto.

Quarto is a publishing system for creating reproducible documents and websites from plain-text source files. It supports multiple output formats, including HTML, PDF, and Word, and integrates naturally with Markdown, Pandoc, and computational content.

Quarto documents are written in Pandoc Markdown syntax, a Markdown flavour that has been extended with some additional features. Together with the Argdown Pandoc filter, Quarto allows you to create documents that combine text, argument reconstructions and argument maps in a single file by using Argdown source blocks.¹ Argument maps will be automatically generated from the Argdown source blocks and included in the rendered document. Similarly, you can include Argdown source blocks displaying, for instance, argument reconstructions that will receive syntax highlighting in the rendered document.

This is a very powerful approach ready at your fingertips. The only downside is that it requires a slightly nerdy setup. To make this workflow easier to adopt, I created a GitHub template that guides you through installation and handles most of the configuration needed to turn a Quarto document with Argdown source blocks into a polished PDF.

The template is available on GitHub at github.com/xylomorph/argdown-quarto-pdf-template. There, you will find a detailed description of how to use the template and set up your environment. In a nutshell:

1. Download the template from GitHub or use it as a template for your own repository.
2. Install Quarto and the Argdown Pandoc filter.
3. Create a Markdown document with Argdown source blocks and add your content.
4. Render the document to PDF using Quarto.

The resulting workflow is therefore quite simple:

1. Analyse in Argdown
2. Document and explain in Markdown
3. Render and publish with Quarto.

@online{cacean2026,
  author = {Cacean, Sebastian},
  title = {Creating Polished PDF Documents With Quarto and Argdown},
  date = {2026-10-07},
  url = {https://sebastiancacean.de/de/posts/quarto-argdown-pdf-documents/},
  langid = {de}
}

Let’s unpack the concepts and features of MAnnoSAS step by step.

First, what is this guideline supposed to be used for? In short, it explains and provides numerous hints to analyse the argumentation structure in argumentative texts, that is texts including argumentation. Typically, argumentative texts contain claims, reasons, arguments, objections, and refutations. The term argumentative component will be used as an umbrella term for these elements.

Argumentative components are usually related to each other by argumentative relations. For instance, an argument is always an argument in favour of some statement, which might be the main claim or the premise of another argument. In this way, an argument can support a claim or another argument. Similarly, an objection is always an objection against some statement. This relation will be referred to as an attack relation.

The argumentation structure of an argumentative text refers to the set of the text’s expressed argumentative components together with the different argumentative relations between them. This structure can be visualised using a reason map. Abbildung 1 is a schematic example of a text in which argumentative components are annotated and where the resulting argumentation structure is visualised as a reason map.

Second, why do we need an annotation scheme? In principle, you do not need a manual to understand the argumentation structure in a text. As competent speakers, we are sufficiently capable of identifying argumentative components and their inter-relationships. However, MAnnoSAS is designed for socio-empirical research contexts. For instance, a scientist might want to analyse parliamentary debates by counting arguments in different speeches. These contexts impose certain scientific criteria on analysts. Ideally, analysing the structure of argumentation would be like a measurement process: concepts and instructions must be precise enough to yield unique results. MAnnoSAS does not provide this ideal precision but helps make analysis results more reliable and comparable across analysts. This analogy leads to the next question.

Third, what is inter-annotator reliability and why does it matter? Inter-annotator reliability is a measure of the degree to which different annotators agree in their analysis. This form of reliability is important in scientific contexts, as it amounts to a form of objectivity, or at least intersubjectivity. If we are, for instance, interested in counting the number of argumentative components in a text, we want to be sure that different analysts will come to the same result. If the result varies across analysts, we do not know whether it reflects a property of the text or is an artefact of the particular analyst.

The criterion of inter-annotator reliability is challenging to meet in argumentation analysis. The analysis of argumentation structure is an interpretive process that can yield divergent results among analysts. The annotator must, for instance, decide whether a text segment is a justificatory reason for a claim or a mere explanatory reason without justificatory relevance. The difference between these two types of reasons is often subtle and requires interpretation. In other cases, the annotator must decide whether a text segment is one compound reason or two separate reasons. Some cases are not clear-cut and require interpretation. MAnnoSAS is tailored to help analysts achieve the same results by providing definitions of key concepts and guidance on their application. While it cannot guarantee uniqueness, its goal is to reduce interpretation and to increase inter-annotator reliability.

Fourth, in which way is this annotation scheme minimalistic? Argumentation analysis is a complex task. There are many ambitious theories and approaches to argumentation analysis, which usually involve reconstructing arguments in premise-conclusion form. Applying these approaches requires expertise and experience. MAnnoSAS is designed to avoid these demanding requirements. It can instruct analysts with no prior knowledge of argumentation theory. It is minimalistic to the extent that it introduces comparably few concepts and avoids overly sophisticated theoretical baggage. In particular, it does not require analysts to reconstruct arguments in their premise-conclusion form. Instead, it focuses on identifying argumentative components and their interrelationships. The goal is to provide a guideline that is easy to use and that allows for reliable identification of argumentative components in text.

If this sounds useful for your own work, I invite you to try MAnnoSAS on a short argumentative text and see how far the guideline takes you. Its purpose is not to eliminate interpretation altogether, but to make analytical decisions clearer, more consistent, and easier to compare across annotators. I hope the manual supports both teaching and research, and I would be very happy to hear about applications, adaptations, or critical feedback.

@online{cacean2026,
  author = {Cacean, Sebastian},
  title = {🔎 MAnnoSAS},
  date = {2026-10-01},
  url = {https://sebastiancacean.de/de/posts/mannosas/},
  langid = {de}
}