Snekdown - More than just Markdown 
Snekdown - More than just Markdown This projects goal is to implement a fast markdown parser with an extended syntax fitted for my needs.
You need a working rust installation, for example by using rustup.
sh
cargo install snekdown
With pdf rendering
sh
cargo install snekdown --features pdf
``` snekdown 0.30.5
USAGE:
snekdown
FLAGS: -h, --help Prints help information -V, --version Prints version information
SUBCOMMANDS: clear-cache Clears the cache directory help Prints this message or the help of the given subcommand(s) render Parse and render the document watch Watch the document and its imports and render on change ```
``` Parse and render the document
USAGE: snekdown render [OPTIONS]
FLAGS: -h, --help Prints help information -V, --version Prints version information
OPTIONS:
-f, --format
ARGS: Path to the input file
```
``` Watch the document and its imports and render on change
USAGE: snekdown watch [OPTIONS]
FLAGS: -h, --help Prints help information -V, --version Prints version information
OPTIONS:
--debounce
ARGS: Path to the input file
```md Simple Syntax !(url)
Extended syntax with a description
Extended syntax with metadata to specify the size
[metadata]
Extended syntax with metadata and no description !(url)[metadata] ```
When generating the html file the images are base64 embedded. To turn off this behaviour
set the config parameter embed-external to false.
```md Simple (default) Syntax
This is a quote
Multiline
This is a Multiline Quote
Quote with metadata (e.g. Author) [author=Trivernis year=2020 display='{{author}} - {{year}}']> This is a quote with metadata ```
Imports can be used to import a different document to be attached to the main document. Imports are parsed via multithreading.
```md <[path]
<[document.md]
<[style.css][type=stylesheet] ```
The parser differentiates four different types of imported files.
document - The default import which is just another snekdown documentstylesheet - CSS Stylesheets that are inclued when renderingbibliography - A file including bibliographyconfig/manifest - A config file that contains metadataIf no type is provided the parser guesses the type of file from the extension.
Tables MUST start with a pipe character |
```md Standalone header: | header | header | header
Header with rows | header | header | header |--------|--------|------- | row | row | row ```
Placeholders can be used to insert special elements in a specific place. Placeholders are always case insensitive.
```md Insert the table of contents [[TOC]]
Insert the bibliography list [[BIB]]
Insert the glossary [[GLS]]
Insert the current date [[date]]
Insert the current time [[time]] ```
Additional metadata can be provided for some elements.
```md String value [key = value]
String value [key = "String value"]
Integer value [key = 123]
Float value [key = 1.23]
Boolean [key]
Boolean [key = false]
Placeholder [key = [[placeholder]]] ```
Metadata can also be defined in a separate toml file with simple key-value pairs.
The file Manifest.toml will always be included by default.
Example:
```toml
[metadata]
language = 'en'
author = 'author'
title = 'title'
description = ''' Description '''
keywords = ['HTML', 'Snekdown']
[features]
embed_external = true
smartarrows = true includemathjax = true
[imports]
ignored_imports = []
included_stylesheets = ['style.css']
included_bibliography = ['Bibliography.toml']
included_glossaries = ['Glossary.toml']
[pdf]
displayheaderfooter = true
header_template = '
'footer_template = '''
page_scale = 1.0
[pdf.margin]
top = 0.5
bottom = 0.5
left = 0
right = 0
[images]
format = "png"
max_width = 700
max_height = 500
[style]
bibrefdisplay = '{{number}}'
theme = 'GithubLight'
[customattributes] customkey1 = "Custom Value" ```
The [Section] keys are not relevant as the structure gets flattened before the values are read.
``` Hide a section (including subsections) in the TOC
Set the size of an image !(url)[width = 42%, height=auto, brightness=10, contrast=1.2, huerotate=180, invert, grayscale]
Set the source of a quote [author=Me date=[[date]] display="{{author}} - {{date}}"]> It's me
Set options for placeholders [[toc]][ordered] ```
|| These two lines
|| are centered
md
*Italic*
**Bold**
~~Striked~~
_Underlined_
^Superscript^
`Monospace`
:Emoji:
§[#0C0]Colored text§[] §[red] red §[]
Bibliography entries can be defined and referenced anywhere in the document.
Definition:
md
Usage:
There is a book about snekdown[^book] and a github repo[^github].
Entries can also be defined in a separate toml file with the following data layout:
```toml
[BIB_KEY] key = "value"
[SD_BOOK] type = "book" author = "Snek" title = "Snekdown Book" date = "20.08.2020" publisher = "Snek"
[SD_GITHUB] type = "website" url = "https://github.com/trivernis/snekdown" ```
The valid types for entries and required fields can be found on in the bibliographix README.
Bibliography entries are not rendered. To render a list of used bibliography insert the
bib placeholder at the place you want it to be rendered.
Glossary entries are to be defined in a glossary.toml file or any other toml file
that is imported as type glossary.
The definition of glossary entries has to follow the following structure
```toml [SHORT] long = "Long Form" description = "The description of the entry"
[HTML] long = "Hypertext Markup Language" description = "The markup language of the web" ```
Those glossary entries can be referenced in the snekdown file as follows:
```md ~HTML is widely used for websites. The format ~HTML is not considered a programming language by some definitions.
~~HTML ```
The first occurence of the glossary entry (~HTML) always uses the long form.
The second will always be the short form. The long form can be enforced by using two
(~~HTML) tildes.
The glossary list can be inserted with the [[GLS]] placeholder.
Snekdown allows the embedding of AsciiMath: The AsciiMath parser is provided in the asciimath-rs crate
``` inline math $$ a^2 + b^2 = c^2 $$
Block Math $$$ A = [[1, 2],[3,4]] $$$ ```
The expression get's converted into MathML which is then converted by MathJax when loaded in the browser.
Snekdown automatically renders the sequences -->, ==>, <--, <==, <-->, <==> as
their respective unicode arrows (similar to markdown-it-smartarrows).
This behavior can be turned off by setting the config parameter smart-arrows to false
(the config needs to be imported before the arrows are used for that to work).
The end goal is to have a markup language with features similar to LaTeX.