PandocFilters 0.3.42

dotnet add package PandocFilters --version 0.3.42
NuGet\Install-Package PandocFilters -Version 0.3.42
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="PandocFilters" Version="0.3.42" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add PandocFilters --version 0.3.42
#r "nuget: PandocFilters, 0.3.42"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install PandocFilters as a Cake Addin
#addin nuget:?package=PandocFilters&version=0.3.42

// Install PandocFilters as a Cake Tool
#tool nuget:?package=PandocFilters&version=0.3.42

PandocFilters

AppVeyor build status NuGet Status

Write Pandoc filters in .NET, using strongly-typed data structures for the Pandoc AST.

Pandoc filters

Pandoc is a command-line program and Haskell library for converting documents from and to many different formats. Documents are translated from the input format to an AST (defined in the Text.Pandoc.Definition module), which is then used to create the output format.

Pandoc allows writing filters — programs that intercept the AST as JSON from standard input, modify the AST, and write it back out to standard output. Filters can be run using the pipe operator (| on Linux, > on Windows):

pandoc -s input.md -t json | my-filter | pandoc -s -f json -o output.html

or using the Pandoc --filter command-line option:

pandoc -s input.md --filter my-filter -o output.html

Pandoc AST

Much of the JSON-serialized AST comes in the form of objects with a t and c property<sup>1</sup>:

{
    "t": "Para",
    "c": [

    ]
}

This corresponds to a Para object with properties filled with the values at the c property.

The library defines types and base classes for both levels:

Type level Description Namespace Visitor base class
Raw Objects with a t and c property PandocFilters.Raw RawVisitorBase
Higher-level AST e.g. Para type PandocFilters.Ast VisitorBase

The library also includes two predefined visitors — DelegateVisitor and RawDelegateVisitor — which can be extended by adding delegates via the Add method, instead of defining a new class (see below for sample).

<sup>1. All the types in pandoc-types except for the root Pandoc type and the Citation type.</sup>

Usage

  1. Create a console application.
  2. Install the PandocFilters NuGet package.
  3. Define your visitor — either
    • write a class that inherits from one of the visitor base classes, and create an instance of the class, or
    • create an instance of the appropriate delegate visitor class, and append delegates using the Add methods.
  4. Pass the instance into Filter.Run.
  5. Either pass your program to Pandoc using --filter; or pipe the JSON output from Pandoc into your program, and pipe the outout back into Pandoc.

Note that Filter.Run takes an arbitrary number of visitors — you can create multiple visitors and pass them into Filter.Run.

Sample

using System.Diagnostics;
using System.Linq;
using PandocFilters;
using PandocFilters.Types;

var visitor = new RemoveImagePositioning();
Filter.Run(visitor);

class RemoveImagePositioning : VisitorBase {
    public override Image VisitImage(Image image) =>
        image with {
            Attr = image.Attr with {
                KeyValuePairs = 
                    img.Attr.KeyValuePairs
                        .Where(x => x.Item1 != "height" && x.Item1 != "width"))
                        .ToImmutableList()
            }
        };
}

Using the delegate visitor:

using System.Diagnostics;
using System.Linq;
using PandocFilters;
using PandocFilters.Types;

var visitor = new DelegateVisitor();
visitor.Add((Image image) => image with {
    Attr = image.Attr with {
        KeyValuePairs =
            img.Attr.KeyValuePairs
                .Where(x => x.Item1 != "height" && x.Item1 != "width"))
                .ToImmutableList()

    }
});
Filter.Run(visitor);

For a real-world usage example with multiple visitors (and the reason I wrote this in the first place), see DlrDocsProcessor.

Credits

Notes

  • PandocFilters is written against the types in pandoc-types 1.22. When pandoc-types is updated, code written against the raw types will successfully receive the JSON-source data structures; while code written against the higher-level types will conceivably fail in the JSON parsing stage.
  • The library uses C# 9 record types (and System.Collections.Immutable) to enforce immutability; otherwise we'd have to check for circular references before serializing. If you're using C# 9 or later, you can use the with keyword to clone/initialize the returned instance; otherwise you'll have to pass in all arguments to the constructor.
Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.3.42 367 12/22/2021
0.3.41 249 12/22/2021
0.3.36 350 1/26/2021
0.3.35 301 1/26/2021
0.3.34 314 1/26/2021
0.3.33 300 1/14/2021
0.3.32 313 1/14/2021
0.3.31 297 1/14/2021
0.3.30 307 1/14/2021
0.3.29 322 1/13/2021
0.3.28 342 1/13/2021
0.3.27 335 1/12/2021
0.3.26 307 1/11/2021
0.3.25 317 1/10/2021
0.3.24 315 1/9/2021
0.3.23 351 1/5/2021
0.2.21 326 1/5/2021
0.2.18 328 1/5/2021
0.2.13 322 12/30/2020
0.1.6 395 12/9/2020