v2.3.0

This minor release brings forth a new feature: bibliographic citations. It also fixes a couple of issues.

New feature

• Basic support for bibliographic citations (#135, #10)

  The Djot language does not officially support bibliographic citations yet, but we have modified the parser to allow for a basic form of citations.

  We have enabled citations too in the Markdown package, following the same syntax as in Djot.

  The supported syntax is a subset of the Pandoc citation syntax:

  • [@key] in the simplest form
  • [@key, page 123] to specify a "locator" (e.g. page, chapter, etc.)
    • The comma between the key and the locator is optional (e.g. [@key page 123] is also valid)
    • Only one locator per citation is supported.
    • The locator must be one of the supported locators in SILE's BibTeX module with CSL support enabled.
    • Some abbreviations are supported by SILE for locators, and here we accept an optional period after it (e.g. [@key, chap. 5] is also valid for full [@key, chapter 5]).
  • Be aware that multiple citations can be separated by semicolons (e.g. [@key1; @key2 page 123]), but due to the limitations of the current implementation in SILE, the output will not be as expected

  How to load bibliographies and configure citation styles is beyond the scope of this module. If you are using the resilient collection of classes and packages, the most natural way to do this is a "master document" (support planned in resilient v2.6.0).

  Also note the CSL (Citation Style Language) support in SILE is a very recent and experimental feature (introduced in SILE 0.15.7), so it may not work as expected in all cases.

Fixes

• Fix broken embedders detection for rendered code blocks (#128, #127)

• Always wrap tables in a captioned-table and let the latter handle a caption if present (#134)

  The captioned-table environment from resilient.book and the fallback environment for other classes always supported tables without caption. It's thus better to always wrap tables into it, so styling (in resilient's use case) is applied, rather than return a raw table, which would not be styled.

Other notes

The User Guide has been updated to reflect these changes.
Many thanks to @kianmeng for the typo fixes in the documentation and in-code comments (#132).
The new version of the User Guide will be available soon, after resilient.sile gets its own update.

v2.2.0

This minor release brings forth a fix, new features and small improvements.

New features

• Djot:

  • Support attributes for numbered display math equations (#81, #124)

    This feature allows users to specify attributes for numbered display math equations, with SILE 0.15 or later.
    Note that a soon-coming release of resilient.sile collection adds styles for the equation numbers, so users can easily customize the appearance of the equation numbers when this collection is used.

  • Support programmatic symbols (extensible via Lua) (#121, #123)

    This feature refactors the internal handling of Djot symbols, and provides a new API method for 3rd-party classes or packages to register their own symbols in addition to the built-in ones.

• Pandoc AST:

  • Support Pandoc 3.1+ implicit figures (Pandoc types 1.23+) (#73, #125)

    This feature improves compatibility with Pandoc 3.1+ (which enables implicit_figures by default and generates a specific node in its AST.)

  • Support the lunajson parsing library as alternative (#21, #104, #119)

    This collection now depends on the lunajson pure-Lua library for parsing the Pandoc AST JSON. It automatically installs it (when installed via LuaRocks), so users no longer have to install a JSON library separately, and can use the pandocast package from this collection out of the box.
    It is still possible for users to install the LPEG-based luajson library, in which case the collection uses it instead. (Note that luajson, at the moment, must be in its development version, as the version distributed via LuaRocks has an issue with recent versions of the LPEG module.)

Fixes

• Common:
  • Use the correct version of the textsubsuper.sile dependency for SILE 0.15 (#120, #122)

v2.1.0

This minor release adds support for SILE 0.15, while still maintaining compatibility with SILE 0.14.11 and later.
However, we strongly recommend upgrading to at least SILE 0.15.5 for the best performance and compatibility.
If you are using an older version of SILE, please upgrade to avoid potential issues.

v2.0.0

This major release brings forth several new features and improvements.

It is major due to updated dependencies, significant code refactoring and modifications to the underlying implementation of various elements (such as insertions and deletions, underlines and strikethroughs, highlights, rendered code blocks, and divs).
However, for the majority of users, these changes should be seamless and have little noticeable impact on existing workflows.

New features

• Common
  • Add a better fallback support for highlighted content (a.k.a. "mark"). (#112, #110)
  • Customizable strike, underline, insertion, deletion and mark. (#112)
    It offers an exact parity between these inline elements (from Djot and Markdown) with spans with a similar class, so both syntaxes are strictly equivalent. When resilient styles are used, this also offers the possibility to fully customize the appearance of these spans.
  • Support bare percentage in width and height key-value attributes (#114, #113)
    It is now possible to specify e.g. width="50%" as an image size, and the converters take care of converting it to width="50%lw" (SILE-specific unit).
  • Generic rendered code blocks are based on raw handlers and embedders. (#112, #111)
    This removes the hard-coded class specifiers, allowing any existing SILE "raw handler" or any "embedder" to be used.
    For instance, if the piecharts package is available, we can render blocks marked as piechart since the package provides a raw handler by that name.
  • CSV file as image source is interpreted as a pie chart. (#112, #111)
    In addition to the generic processing on code blocks mentioned above, it allows using an external CSV pie chart file.
• Djot
  • (Djot extension) caption on Div blocks. (#112)
    We already added caption support on block quotes earlier. This adds it too for divs, interpreted as captioned figures.

Fixes

• Djot:
  • Improve error handling in Djot to report location details (#109)

Other notable changes

The documentation has been completely overhauled, providing more thorough installation instructions.
The primary focus is now on Djot, presented first with a comprehensive description of its syntax, and many examples.
Following Djot, Markdown is introduced, along with notes highlighting its differences from Djot.

v1.5.2

This is a patch release for compatibility with silex.sile v0.4.

Fixes

• Do not load the resilient base class for feature detection (#108)

Notes

This is kind of a workaround for the general breaking issue (#107), but with markdown.sile 1.5.2 and silex.sile 0.4.1, only the minimal features from sile·x are now loaded (BCP47 support and AST utilities), without enforcing the other "possibly breaking" features here.

It should make this module play a bit better with non-resilient classes.
This being said, SILE 0.14.16 still has a multiple package instantiation issue which was avoided by sile·x... So your mileage may vary. The labelrefs package dependency, in particular, is suspected to behave poorly when loaded multiple times in some scenarios.

Using the resilient.sile module is strongly recommended, and the only officially supported workflow.
If you meet issues with other workflows, there's no guarantee they'll be addressed, unless you propose clean PRs.

v1.5.1

This is just a patch release with better compatibility for Lua "minimum" profile, ensuring the module works with Lua 5.1 -- and most of all LuaJIT 2.x, since SILE is moving towards that target.

Many thanks to @alerque on the topic.

Fixes

• Lua 5.1 minimum compatibility (#102)

v1.5.0

This minor release introduces a few new features.

It provides a Djot extension for symbol-based conditionals.
Such "Djot templates" are notably used by resilient.sile version 2.2 to generate customizable "book matter" pages.

Reciprocally, version 2.2 of the resilient.sile collection introduces new environments for definition lists and verbatim text, which are now used when available. This offers the ability to easily style and customize such elements.

New features

• Common

  • feat: Use resilient.verbatim if available and refactor verbatim calls (#98)
    We now use the verbatim environment provided by the resilient.verbatim package, when available, instead of SILE's default implementation, to benefit from its styling features.
  • feat: Support class- or package-provided definition environment (#99, 100)
    This notably allows using the definition environment provided by the resilient.defn package, and to benefit from its styling features.
  • feat: Improve resilient class detection (#96)
    Contributed by @nawordar, this internal change is mostly for class developers wanting to use a resilient class as their base class.

• Djot

  • feat: Djot extension for symbol-based conditionals (#93)
    As earlier versions introduced user-defined symbols, this Djot non-standard extension now allows using such symbols as conditionals, for example to conditionally include a block of text depending on the presence of a symbol.
  • feat: Support more decorative pendants in Djot (#95)
    This allows using other pendants from the couyards.sile collection.

Other notable changes

As usual, the documentation also received a number of improvements. Notably, it now uses a resilient master document with book matter pages and covers (#97).

A few 3rd-party dependencies are updated. Notably, the silex.sile dependency is upgraded. Be aware that the latter overrides some of the core SILE components, changing their behavior — normally for the better, but it may break some workflows.

v1.4.2

This patch release fixes a few bugs.

Fixes

• Common:
  • Fix: Hard breaks do not work well in centered or ragged-left blocks.
  • Fix: Horizontal rules are too thin for print and inconsistent.
  • Fix: Propagate header shifting and metadata to embedded rendered blocks.
• Djot:
  • Fix: Soft breaks may leave multiple spaces in the output.

Other noteworthy changes

• Djot:
  • Propagate positions in Djot input source (for better error reporting).
• Common
  • Update silex.sile dependency from 0.1.0 to 0.2.0
    N.B. If you were using this module with the resilient.sile v2.1 collection, the latter already required that dependency.
    So this is a change only if you were using this module alone, in which case you will indirectly benefit from a few new features, e.g. emphasis nesting and improved centered and ragged (left, right) environments.

v1.4.1

This patch release fixes a few bugs.

It's also the first release where all dependencies are versioned on LuaRocks, so that you can now install them without the --dev option and get the required versions of each component.
This should make it much easier for you to install or upgrade the package collection, and get all dependencies right:

luarocks install markdown.sile

Fixes

• Djot
  • Fix: Handle attributes on note references in Djot (#89, #90)
• Common
  • Fix: Honor qualified BCP47 language to get correct smart quotes (#91, #92)

v1.4.0

This minor release introduces two new exciting features.
And it's an anniversary release.

New features

• Common
  • Header shifting option for Markdown, Djot, Pandoc AST (#86)
    When including or embedding content, you now have the ability to shift the headings. So included "chapters" may become "sections", etc. If your document class supports it, it also allows accessing levels above the usual scheme, such as "parts" with the resilient book class.
• Djot (extensions)
  • Predefined symbols and external metadata passing in Djot (#87)
    In the previous version, we already used Djot symbols in original ways. When including or embedding content, you now have the ability to pass metadata from the upper "wrapper" document and access them via symbols.
    A few predefined symbols are also available: for inserting a table of contents, and as a convenience for typesetting Unicode characters by their code points.

Fixes

• Djot
  • Fix incorrect header identifiers in nested blocks (#83, #84)
  • Fix bad priority between alpha- and roman-numbered list items (#85) (backport)
• Markdown
  • Fix references and notes in fenced divs (#82) (backport)

The documentation also received a number of fixes, rewrites and improvements.

An anniversary release...

Around mid-July 2022, I started overhauling SILE's native Markdown support, initially as a PR under the aegis of the SILE organization; later as this 3rd-party collection of packages, due to the amount of dependencies it involved and the design choices that had to be made.

One year later, after a bunch of contributions to the SILE typesetter and to the Lunamark library, I am quite happy with the result of this effort. As an early adopter of Djot, I also enjoy its capabilities and its extensibility; and I am glad it turned out just when it was the right moment for it to be included in this collection.

After trying this collection, if you enjoy it as much as I do, please add a "Star" ⭐ to its GitHub repository. It's important, for its visibility first of all, and also for myself to feel this is useful to other peoples. You are also welcome contributing to the GitHub discussions or reporting issues.