80 lines
3.1 KiB
Markdown
80 lines
3.1 KiB
Markdown
# md2tufte
|
|
|
|
A custom markdown to html + pdf compiler; based on Tufte CSS.
|
|
|
|
To build all files run `make all` (or `make file.html`, `make file.tex`, `make file.pdf` respectively). Refer to the Makefile to learn what it does.
|
|
|
|
Look at the [example pdf](https://relikd.github.io/md2tufte/en-example.pdf) and [example html](https://relikd.github.io/md2tufte/bin/en-example.html) output built from the [markdown input](en-example.markdown) file.
|
|
|
|
## Requirements
|
|
|
|
You'll need:
|
|
|
|
- [pandoc](https://pandoc.org/installing.html)
|
|
- [Python 3](https://www.python.org/download/releases/3.0/)
|
|
- xelatex
|
|
|
|
Included in the package:
|
|
|
|
- [Tufte CSS](https://edwardtufte.github.io/tufte-css/)
|
|
- Font [Cochineal](https://www.ctan.org/pkg/cochineal), by Michael Sharpe
|
|
- Font [Roboto](https://github.com/googlefonts/roboto), by Christian Robertson
|
|
- Font [Iosevka](https://github.com/be5invis/Iosevka), by Belleve Invis
|
|
|
|
## Usage
|
|
|
|
The format is mostly markdown, except for these modifications:
|
|
|
|
- Use `\,` to insert a non-breaking thin-space.
|
|
|
|
- To insert a normal-width non-breaking space use the actual character.
|
|
on macOS: `Alt + Space`, on Linux: `???`, on Windows: `???`.
|
|
|
|
- Use `\newpage` to start a new page in latex (which is ignored in html)
|
|
|
|
- It supports the latex `\begin{description}` environment by using the html equivalent `<dl><dt><dd>`
|
|
|
|
- The header always begins and ends with a line of at least five colons `:::::`
|
|
- Each line inside the header has the format `KEY: VALUE`
|
|
- Whitespace around the key and value is discarded
|
|
- Each key is replaced in the template file. The placeholder has the format `<#_KEY_#>`
|
|
- Don't use the `BODY` key, as it is reserved for the generated content
|
|
- No other lines (including blank lines) are allowed. Except multi-line variables.
|
|
- Each ML-variable begins with ` KEY : @@@ ` and ends with a line of just three at-signs (regex: `^@@@$`). No whitespace allowed.
|
|
- multi-line variables may contain a line of colons (the header terminator is ignored here)
|
|
|
|
- You can add a reference to a title by adding `{#label}` after the title, e.g., `## Title {#title}`
|
|
- other than that, all titles have implicit labels where spaces are replaced with dashes `My Title` becomes `my-title`
|
|
- btw., you could also add classes this way `{.fullwidth}`
|
|
|
|
- The file prefix, e.g. `en`, is the template file identifier. This can be used for multi-language generation or different types of webpages.
|
|
|
|
- Use `@== content ==@` to place something in the border margin.
|
|
- multi-line content is allowed.
|
|
- to show something in the pdf version only, use `@=latex=` as the prefix. If set, the content will not appear on the html version.
|
|
|
|
|
|
## Limitations
|
|
|
|
This script has not been tested on Linux or Windows. However, Linux should work fine ... in theory.
|
|
|
|
### Known Issues
|
|
|
|
__#1__: If using URLs ins the margin, adding a newline before the href will add an unwanted space. e.g.:
|
|
|
|
```
|
|
@==
|
|
[multi line, super long name desc!](multi-line-url)
|
|
==@
|
|
```
|
|
|
|
will become:
|
|
|
|
```
|
|
| multi line,
|
|
| super long
|
|
| name desc!
|
|
```
|
|
|
|
Fix for __#1__: place the beginning of the url on the same line `@==[]()...` (does not have to be closed on the same line)
|