ZMarkdown

This repository contains all the plugins for ZMarkdown, the Markdown engine powering Zeste de Savoir.

It is a collection of packages extending the remark processor and its MDAST syntax tree, rehype (for HTML processing) and textr (text transformation framework). It also provides MDAST to LaTeX compilation via rebber (and its plugins).

Currently, all the plugins provided only work for remark versions lesser than 13.0.0 (i.e. previous to micromark). While we intend to switch to the new system, no due date has been planned, and it requires a significant amount of work, so please be patient, or, even better, help us making the switch!

Install

Prerequisites

node >= 18
npm >= 9

Installation

git clone git@github.com:zestedesavoir/zmarkdown.git
npm install

This project uses Jest for testing. It is recommended to use the locally installed version using npx, and run Jest in watch mode when developing npx jest --watch --notify (--notify sends desktop notifications when tests run).

Useful commands

npm run test : tests all packages.
npm run clean : clears local dependencies, reinstalls the project and runs all tests.
npm run lint : runs eslint to check the syntax of the full codebase.
npm run build : builds packages using babel.
npm run build -- --scope=<package> : same as above, but builds only <package>.

Packages

mdast-util-split-by-heading

A MDAST tool to split a markdown tree into list of subtrees representing the chapters. It relies on heading depth.
rebber

transformation of MDAST into latex code. This code must be included inside a custom latex to be compiled. Have a look at https://github.com/zestedesavoir/latex-template/blob/master/zmdocument.cls to get a working example.
remark-abbr

This plugin parses *[ABBR]: abbr definition and then replace all ABBR instance in text with a new MDAST node so that rehype can parse it into abbr html tag.
rehype-footnotes-title

This plugin adds a title attribute to the footnote links, mainly for accessibility purpose.
rehype-html-blocks

This plugin wraps (multi-line) raw HTML in p.
remark-align

This plugin parses custom Markdown syntax to center- or right-align elements.
remark-captions

Allow to add caption to such element as image, table or blockquote.
remark-comments

This plugin parses custom Markdown syntax for Markdown source comments.
remark-custom-blocks

This plugin parses custom Markdown syntax to create new custom blocks.
remark-emoticons

This plugins replaces ASCII emoticons with associated image. Compatible with rehype
remark-escape-escaped

This plugin escapes HTML entities from Markdown input.
remark-grid-tables

This plugin parses custom Markdown syntax to describe tables.
remark-heading-shift

Allows to shift heading to custimize the way you will integrate the generated tree inside your application.
remark-heading-trailing-spaces

This plugin removes trailing spaces from Markdown headers.
remark-iframes

Allows to add iframe inclusion through !(url) code.
remark-kbd

This plugin parses custom Markdown syntax to handle keyboard keys.
remark-numbered-footnotes

This plugin changes how mdast footnotes are displayed by using sequential numbers as footnote references instead of user-specified strings.
remark-sub-super

This plugin parses custom Markdown syntax to handle subscript and superscript.
typographic-colon

Micro module to fix a common typographic issue that is hard to fix with most keyboard layouts.
typographic-permille

Micro module to replace %o with ‰ and optionally replace the preceding space.
zmarkdown

Fully integrated package to be used in zeste de savoir website