Opinionated wrapper around pandoc to convert Markdown files into PDF's, office documents (odt, docx) and slide shows. The main idea of rsmooth is to define all the needed informations in the Front Matter (a YAML header within the markdown document) thus no external configuration is needed.
To allow for even more flexibility it's possible to run the content of your input file trough Terra (a templating language very similar to Jinja2). This allows you to tweak the content of your pandoc input. Currently rmsooth can convert markdown files into PDF's, OpenDocument Text (.odt), Office Open XML Document (.docx) and slide shows using Reveal.js. Beside using pandocs default mechanism of creating PDF's, it's also possible to use LibreOffice.
If you have cargo installed simply call:
shell script
cargo install rsmooth
You can download the binary in the release section. Currently only the binary for Linux x86_64 is available (others should be follow shortly).
This section will outline the most used work flows and options. Calling rsmooth with the --help flag will show all available functions.
Take this simple file as a example (example.md):
```markdown
title: A Sample Document author: John Doe
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor. ```
To create a PDF based on this file call:
shellscript
rsmooth example.md
This will create example.pdf. If you want to specify another name of the PDF use the -o flag. The look of the resulting document is defined by the pandoc template specified by the template field in the YAML head. The path to the template file can either be relative or absolute; rsmooth also supports environment variables (like $HOME) and tildes as an abbreviation for the home path (shell expansion).
As stated above rsmooth also supports the creation of odt, docx documents and reveal.js slide shows. This can be tweaked by setting the --format (or -f) flag to one of the following values:
--format pdf Outputs a PDF. You can alter the engine used by setting the engine in the document header (hint: this currently defaults to xelatex).--format odt Outputs the document as a OpenDocument Text (commonly known as odt) office document. You can alter the appearance of the document by setting the reference in the document header. (Note: Currently the template field is ignored when exporting to odt).--format docx Saves the document as a Office Open XML Document (aka a docx). You can alter the appearance of the document by setting the reference in the document header.--format odtpdf Will first export your document as a odt file and then using your LibreOffice installation converting this into a PDF. As with the other office-document based work flows you can use the reference field to alter the appearance of the result.--format reveal Using reveal.js rsmooth can export your document as a slide show. Don't forget to specify the path to the reveal.js assets with the revealjs-url field in your document header. Pandoc's template capabilities gives you a lot of flexibility to control the output. But sometimes there is the need to have more control about the input side of things. This is why rsmooth allows you to alter the markdown input using the Terra template engine. You can enable Tera by setting the dotera and teracontext passing additional data (pleas read the documentation of the respective fields to learn more). You can learn more about the usage of Tera in their documentation. Short example:
main.md:
title: Tera Example dotera: True teracontext: foo: Fnord shopping: - name: Eggs amount: 6 - name: Bread amount: 2 - name: Milk
The content of the context variable foo is »{{ foo }}«. My shopping List:
{% for item in shopping %} - {{ item.amount}}x {{ item.name }} {% endfor %}
{% include "section.md" %} ```
section.md:
```markdown
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla a commodo urna. Aliquam elementum molestie tempor. Suspendisse potenti. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Etiam sed ornare ipsum, in condimentum velit. ```
Calling rsmooth main.md will produce the following pdf:
The application can create an example markdown file showcasing some of the functionality of rsmooth.
shell script
rsmooth example-file -o example.md
Saves the content to the example.md file. Calling without the -o flag will output the example file to the STDOUT.
By using the YAML header (front matter) you can alter the behavior of rsmooth and use additional features.
Note: The whole content of the YAML header will be also available to pandoc and can thus be used in the template files using the $VAR_NAME$ syntax.
Rsmooth tries to resolve a variety of paths used in the configuration header. As they will get shell expanded you can use environment variables and tildes (~) for your home directory. Relative paths will be handled relative to the input file's location. Note: Only fields documented below support this path resolving mechanism.
Field Name: template
Description: Path to the template file. Learn more about these files in the pandoc documentation. If no template is given the default template of pandoc will be used. The template field currently gets ignored when exporting documents as odt or docx.
Type: String (path).
Default: None.
Field Name: reference
Description: Path to a ODT or docx file as a style reference. Learn more in the specific writer options on the --reference-doc option and it's usage.
Type: String (path).
Default: None.
Field Name: engine
Description: Name of the LaTeX engine used to create the PDF document. This internally will set the --pdf-engine option of pandoc.
Type: String.
Default: xelatex (as this is what I'm working with).
Field Name: pandoc_options
Description: Feed additional options into the pandoc call. Multiple arguments are expressed as a list of strings.
Type: String / List of Strings.
Default: None.
Field Name: do_tera
Description: States whether the markdown input should be passed trough the Terra template engine. This allows you some additional flexibility over your input which cannot be achieved by tweaking the pandoc template file. Especially useful to split the content of your document into multiple markdown files and including them using the {% include "section_01.md" %} syntax of Tera. You can pass information to Tera using the Tera Context field. You can learn more about the syntax of Tera in it's Documentation.
Type: Boolean (true/false).
Default: False.
Field Name: tera_context
Description: Sometimes it can be useful to pass some additional information to the Tera engine (context). This can be done by giving this field a map (dict) of strings to any type supported by YAML (learn more about maps in YAML here).
Type: Map String to Any.
Default: None.
Field Name: bibliography
Description: Path to the file containing the bibliographic metadata used for citation within your document. Pandoc supports BibLaTeX, BibTeX, CSL JSON and CSL YAML files. Learn more on how to use this functionality in the pandoc documentation. Note: In order to use the citation functionality of pandoc pandoc-citeproc has to be installed on your system.
Type: String (path).
Default: None.
Field Name: csl
Description: Path to the Citation Style File describing the style of citations within the document.
Type: String (path).
Default: None (pandoc will use the Chicago Manual of Style author-date format).
rsmooth assumes the pandoc executable is callable with the pandoc command. You can use the environment variable PANDOC_CMD to alter this.
The location of LibreOffice defaults to soffice and can be changed using the LIBREOFFICE_CMD environment variable.