package stone

v0.6

This is a major overhaul release, which includes a number of breaking changes. See below for a migration guide.

High-level changes (breaking changes highlighted):

• The configuration file format has changed to .toml, the name of the file is now stone.toml (was previously config.stone).
• The data/ folder has been removed. Instead, a new templates/ directory is introduced to contain template files. Other static files should go in pages/ (e.g. pages/static/). There is no special handling of static files anymore..
• Page titles can now be specified in the config for any page, instead of only header pages; see the documentation.
• The mechanism for custom "exporters" and custom templates has been generalized. The configuration now specifies a list of "rules"; see the documentation for more details.
• In templates, the CSS variable has been removed. Instead, a more general PATH_TO_ROOT variable is provided. See the documentation.
• Switch to the Cmarkit library for rendering markdown. This may change the HTML ids generated for headings and used in anchors, check your links.
• Removed the template generated by stone -i for mlorg.
• Stone is much faster (~20x) after fixing its naive file copy implementation.
• NB: the loading of fonts was fixed in the recent 0.5.2 release, resulting in visual changes if you were previously relying on the fallback fonts.

Migration guide

• mkdir templates and move your templates from data/ to templates/
• move remaining files in data to pages/static/; then rmdir data/
• edit your templates, replace $CSS$ by <link href="$PATH_TO_ROOT$static/style.css" type="text/css" rel="stylesheet">
• if you used the default style.css or templates, be sure to check the updated version (style.css, template) for any changes that you need to backport.

• create a minimal stone.toml by copying the default file. Then:

  • Title (in config.stone) becomes title (in stone.toml)

  • Items of Pages must be split into the header and page_title settings. Additionally, path to files now refer to the files after processing rather than before. For example, Pages = [("index.md", "Home")] becomes:

        header = ["index.html"]
    
    [page_title]
    "index.html" = "Home"

  • DefaultTemplate corresponds to the template setting in the default [[rule]] block for markdown.
  • if you have custom Exports or PagesTemplates, you need to define custom rules. See the documentation on rules.
  • ExtraStatic is gone, static files should be put somewhere in pages/ and will be copied as-is.
  • DirPerm and FilePerm are gone; their previous default value is now used in all cases.
• check any known links to the headers of your pages; header ids may have changed with the switch to cmarkit. See the documentation on markdown.