diff --git a/chapters/configuration.md b/chapters/configuration.md new file mode 100644 index 0000000..ce17591 --- /dev/null +++ b/chapters/configuration.md @@ -0,0 +1,183 @@ +# Configuration + +Some attributes of a Snekdown document can be controlled by using a configuration file. +The default name for this file is `Manifest.toml`. When importing a `toml` file, it gets interpreted +as a configuration file by default. Multiple configurations are combined. + + +The basic layout of the manifest file is the following: +```toml +# document metadata +[metadata] + +# features used in the document +[features] + +# additional imports and blacklists +[imports] + +# settings related to pdf rendering +[pdf] + +# image settings +[images] + +# Visual adjustments +[style] + +# custom metadata +# String -> String Mappings +[custom_attributes] +``` + +## Metadata + + The metadata sections allows for configuration of document metadata. +It currently supports two keys: + +```toml +[metadata] +# language setting of the document +language = 'en' + +# author of the document +author = 'author' +``` + + +## Features + +The features section provides options to turn off some snekdown features. +The provided options are: + +```toml +[features] + +# if external sources (images, stylesheets, MathJax) +# should be embedded into the document (default: true) +embed_external = true + +# If SmartArrows should be used (default: true) +smart_arrows = true + +# If the MathJax Library should be included. +# Without this library the math rendered by snekdown won't be displayed +# correctly in browsers that don't support MathML (for example Chromium based browsers). +# (default: true) +include_mathjax = true +``` + + +## Imports + +The import section allows the definition of additional imports and imports that +should be ignored. + +```toml +[imports] +# those files won't get imported +ignored_imports = [] + +# stylesheets that should be included +included_stylesheets = ['style.css'] + +# bibliography that should be included +included_bibliography = ['Bibliography.toml'] + +# glossary that sould be included +included_glossaries = ['Glossary.toml'] +``` + + +## PDF + +In the pdf section, some settings related to the PDF Rendering can be tweaked. + +```toml +[pdf] + +# If the header and footer of the pdf should be displayed (default: true) +display_header_footer = true + +# PDF header template of each page (default: '
') +header_template = '' + +# PDF footer template of each page (default: the value below) +footer_template = ''' +