# Release Notes 2019
# v1.3.0 (December 2019)
Changes in: @argdown/core, @argdown/node, @argdown/vscode, @argdown/sandbox, @argdown/codemirror-mode, @argdown/prism, docs
New package: ArgVu
This release fixes all currently open bugs, introduces ArgVu (opens new window), a font for Argdown, and configurable shortcodes (opens new window) for special characters like logical symbols or emojis.
ArgVu (opens new window) is a free font that adds Argdown-specific font ligatures and glyphs to DejaVu Sans Mono (opens new window). You can configure VSCode so that it will only use ArgVu ligatures for Argdown files. For a feature list and installation instructions consult the font's README (opens new window).
# Shortcodes for logical symbols and emojis 😍
You can now use shortcodes like
.A. for ∀ or
:happy: for 😀 instead of having to copy and paste special unicode characters. Please read more about this feature in our guide on creating argument maps (opens new window).
If you install ArgVu and use its
dlig ligatures the shortcodes for logical symbols will be automatically displayed as their unicode counterparts (so :A: will look like ∀ and :<->: will look like ↔). It is just like magic!
# Bug fixes
- Multiple empty lines at end of file #132
- First line empty, second line comment #130
- Language server throws error messages in VS code #128
- Windows line feed (\r) in argdown cli prevents it from running on linux #121
- VS Code: language server does not work with unsaved files #89
# v1.2.0 (October 2019)
Changes in: @argdown/core, @argdown/node, @argdown/vscode, @argdown/sandbox, @argdown/language-server, docs
This is a small maintenance release that updates the packages dependencies, fixes the current bugs and improves the way linebreaks behave in statements and argument descriptions.
# Line breaks and empty spaces
Until now, line breaks were simply ignored by the parser. As @sbrugman pointed out in #117 (opens new window) the standard Markdown behaviour is that single line breaks in a paragraph are interpreted as empty spaces. Argdown will now behave in a similar way if
- the line break is not already preceded by an empty space
- the line break does not finish the statement text or argument description.
# Bug fixes
- Windows line feed (\r) in argdown cli prevents it from running on linux #121
- 3 *s cause problem #118
- Add support for implicit relation direction of undercut (_ instead of <_) #112
- error in installation instructions for @argdown/cli #120
- link to first example broken #115
- make docs more welcoming for users not familiar with argument maps #114
- Documentation: Broken Link to @argdown/cli Readme and API docs #108
- argdown-vscode: Update icons #122
# v1.1.0 (March 2019)
Changes in: @argdown/core, @argdown/node, @argdown/vscode, @argdown/sandbox, @argdown/language-server
This is a big release that extends the Argdown packages with a number of useful new features and configuration options like
- the new GraphML export for yEd,
- closable groups,
- support for rank assignment in dot,
- improved hover quick info in VSCode,
- a dark Argdown theme for VSCode
However by far the most effort was put into bug fixes and improvements in code quality and stability. Nearly all bug issues on Github are now closed and all three Argdown apps should have gotten better in handling invalid Argdown code.
# GraphML Export
Maps can now be exported to GraphML (opens new window). The exported maps can directly be used in the powerful and free yEd (opens new window) graph editor. This makes it now possible to completely customize the graph layout and design of the map.
The map in GraphML will not be layouted, all nodes have the same position. After the import in yEd you have to apply a graph layout (this only takes a few clicks).
# Closable Groups
A group can be closed now to hide all its children. This is useful to reduce complexity in huge maps.
# Usage with Data Flag:
# Usage in Group Configuration:
group.sections setting allows to define which sections are closed and which are not groups:
This allows to use headings as groups without "polluting" the Argdown document with data flags.
# Usage in Regroup Configuration:
# Ignoring Group Data flags
Group data flags can now be ignored by using
# Dot Configuration: Rank Assignment
For the Dot export and VizJs map you can now use the
sameRank option to declare that certain nodes should be at the same level in the layout (see this Stackoverflow question (opens new window) for an example).
# Usage of the
sameRank Setting in Dot Configuration
# Usage of the
rank Property in Element Data
If you want to put nodes of different groups (clusters) into the same rank, you might want to try the
newrank graphviz setting (opens new window):
See this Stackoverflow question (opens new window) for more information.
# VizJs Configuration: Layout Engines
VizJs can now be configured to use any of its layout engines (opens new window):
- dot (default)
At the moment this will not work on https:argdown.org/changes as the documentation still has to use an outdated VizJs version for technical reasons. If you want to try it out, copy the code below into the browser sandbox or into VSCode.
# Dot/VizJs/Dagre Configuration: Changing the Node Width
The dot export/VizJs map and Dagre map now support two methods of changing the node width.
In both cases the Argdown app has to add line breaks to the node labels to force a certain node width. The node width is changed by customizing the method by which the line breaks are added.
By default a line break is added after a certain maximum number of characters (respecting word boundaries). This behaviour is customized by using the
charactersInLine setting. This simple method is fast and works surprisingly well in practice.
Here is an example of customizing the dot export with different
charactersInLine settings for groups, arguments and nodes:
Note that you have to define separate
charactersInLine settings for the title labels and text labels of argument and statement nodes. This is necessary because you can also use different font sizes for them, so you might want to set
charactersInLine lower if the font size is larger.
Alternatively, you can try a more exact and slower method by turning on
measureLineWidth. In this case the actual pixel width of each word is measured and a line break is added after a certain maximum number of pixels (once again respecting word boundaries).
This behaviour is customized by using the
lineWidth setting. Here is an example of turning on and customizing
measureLineWidth for the VizJs map:
In this case there are no separate settings for title and text as the line width is measured by taking different font sizes into account.
For the text measurement we use the string-pixel-width (opens new window) library to be able to measure text outside of the browser. Please note that the library only supports measuring a limited number of fonts, so this option might not work with your font. Please consult the library's Readme (opens new window) for further information.
# Dot Configuration: Using
minWidth to Set a Uniform Minimum Node Width
In the dot export (and the VizJs map by extension) the
minWidth property will be used as a minimum node width. If
minWidth = 0 the default GraphViz behaviour will be used, which means that the node width is set to
maxLineWidthInLabel + horizontalMargin. This is how nodes widths were determined before in the Argdown VizJs map. This behaviour saves space, but it has the downside that nodes have different widths, depending on their label content. This lack of uniformity might make the map look messy.
In the new version, Argdown sets the minWidth for argument and statement nodes by default to
180 which means that the node width is now set to
max(180, maxLineWidthInLabel) + horizontalMargin. If you want the old behaviour back, you have to set
minWidth to 0.
Here is the new default behaviour:
Here is how you get the old default behaviour back:
# Dot Configuration: Setting Margins for Nodes and Groups
You can now use the
margin dot setting to customize the sizing of statements, arguments and groups in dot (and the VizJs map):
# GraphML Configuration: Node Size
Because the GraphML export is not used in a live preview, performance is not as important so it always uses the line measurement method.
In contrast to the Dot export and the Dagre map, node width can be set directly. Together with the
horizontalPadding setting it determines the node's line width.
Here are the node size configuration options for GraphML:
# Dot/GraphML/Dagre Configuration: Font Style
Font size, font and boldness of text in the Dot/GraphML exports and VizJs/Dagre maps can now be customized for groups, arguments and statements:
# Color configuration: Custom Relation & Edge Colors
Relation colors can now be customized. Here is how you can turn all attack edges in your map pink:
# HTML Export: Creating a Header From Document Metadata
The HTML export now uses frontmatter metadata to create a document header with a title and optionally a subtitle, authors, date and abstract:
If you want to define metadata, but not generate a HTML header section, you can deactivate this feature in the html settings:
# PDF Export Configuration
The PDF export for the VizJs map is now fixed. The size and padding of the pdf can now be changed. The map will be scaled accordingly.
For VSCode users: please note that only the currently visible part of the map will be visible in the pdf file. If you have zoomed in, some parts of the map will be cut off. Reload the map to make all nodes visible again and then export to pdf without zooming.
# Dot Configuration:
To support VSCode dark themes the VizJs map's background color is now set to
transparent. You can change the background color with the
Here is how you turn your VizJs map background pink:
# Changes in Section Assignment
The behaviour of the section assignment has slightly changed: If an equivalence class has no definition and an argument has no definition and no premise-conclusion-structure the section of their first reference is assigned to them:
Previoulsy no section was assigned in these cases.
# VSCode: New Themes
The VSCode Argdown extension now comes with two themes:
- Argdown Light, based on the default light theme
- Argdown Dark, based on the default dark theme
Additionally the extension's README now contains instructions how to use any VSCode theme with Argdown by adding custom token colors to your VSCode configuration.
The Argdown preview will now also use your current theme's colors for its styles, so that the extension will be seamlessly integrated into VSCode.
# VSCode: Hover Quick Info
Hovering with the mouse over statement and argument titles will show an improved quick info view that will show explicit and now also implicit relations that can be derived from equivalence classes and premise-conclusion-structures.
# VSCode: Persistent Preview
The Argdown preview will now serialize its state and recreate it on VSCode restarts, allowing you to continue work where you left off. This also applies to its zoom state.
# Minor changes
- @argdown/vscode: added argdown.preview.minUpdateDelay setting so that the user can increase the delay between preview updates if performance is an issue
- @argdown/core: simple configuration data sanitization system for better stability in previews if configuration is invalid
- @argdown/core: checkResponseInputFields helper for easier response validation in plugins
- @argdown/core: added error code to plugin exceptions for easier testing of exceptions handling
- @argdown/language-server: increased general stability (exception handling)
- @argdown/sandbox: increased general stability of preview (catching exceptions), VizJs is now automatically reinstantiated if rendering fails
- @argdown/vscode: now uses Viz.Js inside the webview, hopefully improving performance
- @argdown/sandbox: now uses a web worker for the VizJsMap that should improve performance
- @argdown/map-views: refactoring of map views, changed Dagre labels from foreign-objects to pure svg to avoid browser bugs
- @argdown/vscode: using @argdown/map-views now, sharing code with @argdown/sandbox
- @argdown/sandbox: using @argdown/map-views now, sharing code with @argdown/vscode
- @argdown/core now exports deriveImplicitRelations helper for getting inferences derivable from pcs (used in hover provider of language server).
- @argdown/core now exports jsonReplacer and stringifyArgdownData for stringifying Argdown data.
- @argdown/sandbox removed settings view (as all configuration should be done via frontmatter)
- updated all dependencies
- @argdown/core (and others): replaced dependency on lodash with dependencies on single lodash functions
# Breaking changes
- Process order: Map colorization now happens in the ColorPlugin, so it needs to be run after the MapPlugin
- renamed dotToSvg to vizJs settings
- removed some cli options in favor of configuration through config file or frontmatter section (see cli help for remaining options)
- VizJsMap now uses the external full.render.js that can be used as a web worker. This file should not be processed by a bundler and has to be made accessible to the map view.
- DotToSvgPlugin runs now asynchronous (using app.run instead of app.runAsync will not run it)
# Bug fixes
- #106 vizjs map can not handle untitled arguments
- #104 Extension host stops in VSCODE
- #103 @argdown/sandbox: dagre nodes twice too large in Chrome
- #99 @argdown/codemirror-mode: highlighting of indented inferences
- #97 Language Server should not send parser errors to log
- #90 argdown-vscode: improve quick info on hover
- #87 Incorrect arrows with: isInMap: false and mode:strict bug
- #82 html export: improve anchor link behavior
- #57 redundant edges in map
- #51 pdf export: map is cut off
# Older releases
For the release notes of 2018 visit this page (opens new window).