Argdown for Visual Studio Code

Argdown is a simple syntax for analyzing complex argumentation, inspired by Markdown. This extension provides full language support for Argdown in VS Code:

• New feature! Full support for argdown.config.json files: The new code-completion, hover info and validation makes it much easier to find your way through the file format and the many configuration options.
• Integration with Markdown: Use Argdown code blocks and see them transformed to argument maps in the live preview for Markdown files.
• Live Preview for Argdown files: See your argument map change during writing Argdown files.
• 2 map layout algorithms (DagreD3 & Viz.js)
• Code completion
• Symbol search, outline and breadcrumb support
• Quick info (hover)
• Folding ranges
• Jump to/peek at references and definitions
• Syntax highlighting
• Linting (Code Diagnostics)
• Export as web component and to Html, Dot, JSON, SVG, PNG and PDF

If you want to learn more about Argdown argumentation syntax, read the guide and documentation.

Working with the extension

VS Code will only load the extension for Argdown documents.

To tell VS Code that your document is an Argdown document, save your document with the .argdown or .ad filename extension (e.g. test.argdown).

Activating Argdown syntax highlighting

Standard themes do not by default highlight Argdown relations and elements. To add complete Argdown syntax highlighting to VSCode you can activate one of the two default themes that are provided by the Argdown extension:

1. Go to File/Preferences/Color Theme (Windows) or Code/Preferences/Color Theme (OSX) in the main application menu
2. Select Argdown Light or Argdown Dark from the list of available themes

These themes simply extend the default VS Code themes, so they will also work with other languages.

If you prefer to work a different theme, you can also add custom Argdown colors to your VSCode configuration that will work with any theme. Please read the section at the end of this document for further instructions.

Using ArgVu font ligatures in VSCode

If you are looking for the perfect font for your Argdown code, check out our free ArgVu font. It comes with Argdown-specific font-ligatures and glyphs. After installing the font, you can activate it in VSCode by adding the following to your settings.json:

    "[argdown]": {
        "editor.fontLigatures": "'dlig'",
        "editor.fontFamily": "ArgVu Sans Mono Regular"
    },

See ArgVu's Readme file for more detailed instructions.

Map Preview

Integration with Markdown

You can use Argdown codefences in Markdown:

# Markdown file

This will initially show the "source" view
of the web component in the Markdown preview:

```argdown
===
title: Argdown
===

[s]
  - <a>
```

This will initially show the "map" view
of the web component in the Markdown preview:

```argdown-map
===
title: Argdown
===

[s]
  - <a>
```

The Argdown code will be correctly syntax highlighted. If you open the Markdown preview the code fences will be exported as web components that allow you to switch between the syntax-highlighted Argdown source code and a zoomable map view (using Viz.js), just like in the Argdown documentation.

Please note that the advanced language features of VSCode (code dianostics, code completion, ...) will not work in the Markdown code fences. If you want to use them, first write your Argdown code in an .argdown file and when your are ready copy & paste it into your .markdown file.

Code Completion

Document Outline, Breadcrumbs and Symbol Search

Exporting

Configuration files

The Argdown extension will help you write argdown.config.json files. Simply save a new file with that name and add curly braces {}. Set the cursor between the braces and press CTRL+Space to use code completion.

VSCode will present you a list of the top-level sections of an Argdown config file. Choose one from the list to add it to your file, for example:

{
  "color": {}
}

Now you can move the cursor between the new curly braces, insert a line break and press CTRL+Space again. VScode will present you a list of the configuration options for the color section. Choose one, for example:

{
  "color": {
    "colorScheme"
  }
}

Add a colon and you will be presented with the names of all built-in color schemes. Pick one and press enter.

{
  "color": {
    "colorScheme": :"iwanthue-blue-ocean"
  }
}

You can also move your mouse over "colorScheme" in your config file and you will get a hover information with a description of this configuration option.

VSCode will also validate your config files and provide you with code diagnostics.

By using code completion, hover infos and validation you can explore the different configuration options available to you. Alternatively, take a look at this configuration cheat sheet.

Adding custom Argdown colors to your settings

If you prefer to work with other themes, you can add custom colors for Argdown elements to your settings:

1. Go to File/Preferences/Settings (Windows) or Code/Preferences/Settings (OSX)
2. Enter colorCustomizations in the search input field.
3. Click on edit in settings.json (this will simply open the file, so it does not really matter that you find the right setting here)

In settings.json we have to add the custom colors to the editor.tokenColorCustomizations setting as described here. For example, here is how we can change the style of all Argdown attacks:

{
  "editor.tokenColorCustomizations": {
    "textMateRules": [
      {
        "name": "Attack",
        "scope": "markup.list.unordered.attack",
        "settings": {
          "foreground": "#C93504",
          "fontStyle": "bold"
        }
      }
    ]
  }
}

You can find the scopes that are used by the Argdown syntax highlighter in the Argdown Light theme. You find the file of the theme here. Simply copy & paste everything from the tokenColors array into the textMateRules array, change the colors according to your taste and you are good to go.

While you are at it you might also want to adjust the colors in the HTML and map previews. To achieve that you can add an argdown.config.json file in your workspace folder and use the color configuration options. Please consult the Argdown documentation for further details.