0.26.0: Improvement to block-based side notes

The approach implemented in 0.25.0 suffered from a problem where notes in nested block elements (e.g., a paragraph inside a list item), would get hoisted all the way to the top of the outermost block element.

This new approach binds the block-based side notes where they were.

I have completely rewritten the filter, but it produces no diff on my blog which uses a mix of all kinds of side notes. Please do report bugs, as always.

0.25.0: Block-based side notes

To avoid having block elements dropped, use {^} or {^-} for block-based
side notes and margin notes, respectively.

By default, side notes and margin notes cannot contain block elements, like
code blocks, lists, or tables. If they do, they are silently dropped.

See #4 and #33 for more discussion of the problem.

Here's an example of the new syntax for block-based side and margin notes:

This side note[^4] and this margin note[^5] can contain block elements.

[^4]:
    {^} There are block elements in this side note:

    - Hello, world!

[^5]:
    {^} There are block elements in this margin note:

    ```python
    print("Hello, world!")
    ```

Note: these two features produce an HTML structure that is currently
only supported by Pandoc Markdown CSS Theme. Notably, Tufte CSS does not
support this structure yet. For implementers, you may want to cross reference
this commit and this commit.

Note: these two features are only supported by the Lua filter, not the
JSON filter.

0.24.0: Lua port

This project provides two, equivalent filters:

• pandoc-sidenote.lua, a Lua filter, which is run invoked internal to the
  pandoc binary. See Lua filters in the Pandoc docs for more.

  This is the preferred way to use pandoc-sidenote.

  The Lua filter is newer than the JSON filter, but I have tested it on a wide
  range of Markdown files and it produces byte-wise identical results.

• pandoc-sidenote, a JSON filter which reads a JSON
  representation of the pandoc AST on stdin and produces JSON on stdout.

  This filter is written in Haskell and compiled to a native executable. It uses
  the upstream pandoc-types library to deserialize the JSON it receives on
  stdin, which means that pandoc-sidenote can only be used with a version of
  pandoc built against the same pandoc-types version. See JSON filter
  dependencies below.

  This is cumbersome, as it means that pandoc-sidenote needs to be rebuilt and
  republished for any new pandoc versions which makes a change to the core
  AST, even if it's a part of the AST that this filter doesn't care about.

The Lua filter (pandoc-sidenote.lua) is the preferred way to use this project.
You can install it globally or local to a project. The Lua filter is a single
Lua file that works on all platforms where pandoc works.

Lua filter, globally installed

Consult the docs for how Pandoc searches for Lua filters.

To install globally:

1. Download pandoc-sidenote.lua

   → pandoc-sidenote.lua

2. Put the file in the Pandoc user data directory. See the Pandoc
   docs for what the data directory is on your system.
   Specify a data directory by passing --data-dir when invoking pandoc.

3. Invoke pandoc like this:

   pandoc --lua-filter pandoc-sidenote.lua [...]
   

As an example, on macOS or Linux, this shell snippet will download and install
the filter globally:

curl --remote-name --no-clobber --create-dirs \
  --output-dir "${XDG_DATA_DIR:-$HOME/.local/share/}/pandoc/filters" \
  -sSL "https://github.com/jez/pandoc-sidenote/raw/refs/heads/master/pandoc-sidenote.lua"

Lua filter, locally installed

Consult the docs for how Pandoc searches for Lua filters.

To install locally:

1. Download pandoc-sidenote.lua

   → pandoc-sidenote.lua

2. Put the file in the Pandoc user data directory. See the Pandoc
   docs for what the data directory is on your system.
   Specify a data directory by passing --data-dir when invoking pandoc.

3. Invoke pandoc like this:

   pandoc --lua-filter ./pandoc-sidenote.lua [...]
   

As an example, on macOS or Linux, this shell snippet will download and install
the filter into the current directory:

curl --remote-name --no-clobber \
  -sSL "https://github.com/jez/pandoc-sidenote/raw/refs/heads/master/pandoc-sidenote.lua"

0.23.0

Support for pandoc 3.0 (pandoc-types 1.23)

0.22.3

Support for pandoc 3.0

0.22.2

New syntax:

This is a sample text file.[^footnote]

[^footnote]: {.} This is a foot note.

Prefix with {.} to leave the footnote markup unchanged.

0.22.1

Now wraps the sidenote in a .sidenote-wrapper class.

0.22.0

Now compatible with pandoc 2.11.

0.20.0

Now compatible with pandoc 2.9.

0.19.0

Now compatible with pandoc-1.19.