From 1b203e0bad5b6704aa42fed5802f36a893b81069 Mon Sep 17 00:00:00 2001
From: trivernis <trivernis@protonmail.com>
Date: Sun, 17 Jan 2021 11:06:48 +0100
Subject: [PATCH] Add configuration section

Signed-off-by: trivernis <trivernis@protonmail.com>
---
 chapters/configuration.md | 183 ++++++++++++++++++++++++++++++++++++++
 main.md                   |   8 +-
 2 files changed, 190 insertions(+), 1 deletion(-)
 create mode 100644 chapters/configuration.md

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: '<div></div>')
+header_template = '<div></div>'
+
+# PDF footer template of each page (default: the value below)
+footer_template = '''
+<div style="font-size: 10px; text-align: center; width: 100%;">
+    <span class="pageNumber"></span>/<span class="totalPages"></span>
+</div>'''
+
+# The scale at which the website is rendered into pdf.
+page_scale = 1.0
+
+# Margin of the document
+[pdf.margin]
+
+# Top margin of the pdf. Should be between 0 and 1. (default: 0.5)
+top = 0.5
+
+# Bottom margin of the pdf. Should be between 0 and 1. (default: 0.5)
+bottom = 0.5
+
+# Left margin of the pdf. Should be between 0 and 1.
+left = 0
+
+# Right margin of the pdf. Should be between 0 and 1.
+right = 0
+```
+
+
+## Images
+
+If you want to change the format or size of embedded images you can 
+do so in this section.
+
+
+```toml
+
+# Force convert images to the specified format.
+# Supported formats are png, jpeg, gif, bmp, (ico needs size <= 256), avif, pnm
+# (default: keep original)
+format = "png"
+
+# the max width for the images.
+# if an image is larger than that it get's resized.
+# (default: none)
+max_width = 700
+
+# the max width for the images.
+# if an image is larger than that it get's resized.
+# (default: none)
+max_height = 500
+```
+
+
+## Style
+
+The style section provides options to tweak the visual appearance of
+the Snekdown document.
+
+
+```toml
+[style]
+# how bibliography references should be displayed
+bib_ref_display = '{{number}}'
+
+# the chosen theme for the document
+# one of: GithubLight, SolarizedLight, OceanLight, SolarizedDark, OceanDark, MagicDark
+theme = 'GithubLight'
+```
+
+
+## Custom Attributes
+
+The custom_attributes section can be used to define custom keys
+that can be inserted as placeholders in the document. The mapping has to be
+a String -> String mapping.
+
+```toml
+[custom_attributes]
+custom_key1 = "Custom Value"
+```
+&nbsp;
\ No newline at end of file
diff --git a/main.md b/main.md
index 08914df..d50ff8f 100644
--- a/main.md
+++ b/main.md
@@ -47,4 +47,10 @@
 
 - - -
 
-<[chapters/glossary.md]
\ No newline at end of file
+<[chapters/glossary.md]
+
+- - -
+
+<[chapters/configuration.md]
+
+- - -
\ No newline at end of file