Skip to content
master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
bib
 
 
 
 
 
 
csl
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

robusta

A sound and versatile pandoc LaTeX boilerplate to produce academic books (in PDF) utilising solely modular Markdown files, featuring YAML, KOMA-Script, BibLaTeX and CSL.

For typesetting an entire book please see the arabica boilerplate.

Thanks

The robusta boilerplate is inspired by the pandoc latex template eisvogel by Wandmalfarbe and was built with the help of the following sources and tools: References and Credits. For other projects like the one at hand please see the list of user contributed templates at the pandoc wiki and the list of pandoc boilerplates at the pandoc wiki.

Features

  1. Simple Your writing process is as simple as possible because you only need to write Markdown files and let the strong defaults of pandoc and LaTeX work for you. (see ./controls/ and ./settings/)
  2. Configurable Your book projects are as configurable as possible because you can set your metadata and variables via YAML files and then reuse them if you want to. (see ./settings/)
  3. Modular Your book projects are as modular as possible because of strict separation of contents and presentation (style). Your content live in separate directory (see ./core/) where you can organise them intuitively. The pandoc template itself lives in ./controls/.
  4. State-of-the-art technology stack and low tech debt at the same time.

Preview

... coming soon ...

Examples

Go to ./examples/ to view a list of complete example book projects.

Install

Preconditions

  1. Install TeX Live or any alternative LaTeX distribution.
  2. Install pandoc.

Clone

  1. Go to your templates directory: cd /path/to/your/templates/.
  2. Clone (or download) this repository git clone https://github.com/qualiacode/robusta.git
  3. Done!

Use

Optional: copy, paste, rename, delete

  1. Copy the entire robusta boilerplate located at your own local templates directory and paste the entire robusta boilerplate to your directory of your own projects directory: cp /path/to/your/templates/robusta/* /path/to/your/projects/projectname/
  2. Go to your project directory: cd /path/to/your/projects/projectname/
  3. Delete all the files you do not need e.g. ./examples: rm -vrf examples/*

Set metadata

  1. Go to ./settings/00_01_metadata.yaml
  2. Set your (meta)data, the more the better.
  3. It is a good idea to add at least one author, a title and a year.
  4. Enclose your values ((meta)data) in single quotes: '()(meta)data)'.
  5. If you want to leave a value undefined enter a tilde.
  6. Example:
title: &title 'Short title'

subtitle: &subtitle ~

author: &author
  - 'Jane Roe'
  - 'John Doe'

year: '2018'

Set variables

  1. You can leave the defaults and you will be fine most of the time.
  2. If you want to change things, then the same rules as in Metadata settings apply.
  3. Go to ./settings/00_01_settings.yaml.
  4. Set your settings.
  5. Example:
classoption:
  - 'twoside'
  - 'twocolumn'
  - 'parskip=full'

custom_title_page: false

...

toc: true

Collect

  1. Do your research, collect your bibliographic data.
  2. Go to ./bib/
  3. Save your bibliographic data in Bib(La)TeX format (.bib) in the file ./bib/.references.bib.
  4. Go to ./settings/00_01_settings.yaml.
  5. Refer to your .bib file by adding the corresponding path of your .bib file as value to the corresponding key.
  6. Example (default):
bibliography: './bib/references.bib'
  1. Example entry in your .bib file:
@article{Cantor1984,
  langid = {german},
  title = {Ein Beitrag zur Mannigfaltigkeitslehre},
  volume = {1877},
  doi = {10.1007/978-3-7091-9516-1_3},
  journaltitle = {Über unendliche, lineare Punktmannigfaltigkeiten},
  date = {1984},
  pages = {25-44},
  author = {Cantor, Georg}
}
  1. In this example your cite key for this bibliographic entry is Cantor1984.

Select

  1. Go to CSL
  2. Dowload your desired citation style language file e.g. chicago-author-date-de.csl.
  3. Save your .csl fiile to: ./csl/
  4. Go to ./settings/00_01_settings.yaml.
  5. Refer to your .csl file by adding the corresponding path of your .csl file as value to the corresponding key.
  6. Example (default):
csl: './csl/chicago-author-date-de.csl'

Write

  1. Go to ./core/ and write you markdown files.
  2. Organise them as you like but keep in mind that pandoc will append them sequentially, determined by the alpha-numeric ordering of your file names.
  3. A good example:
01_introduction.md
02_mainpart.md
03_conclusion.md

Cite

  1. Cite your sources by adding your refercences via [@citekey] to your markdown file(s) where ever you need them.
  2. Example:
„Cantor once said: ‚Wenn zwei wohldefinirte Mannigfaltigkeiten ...‘ [@Cantor1984]“

Run

  1. Execute pandoc with the following options:
pandoc                                                                      \
  -s                                                                        \
  -o ./output/projectname.pdf                                               \
  --data-dir=$HOME/path/to/your/projects/projectname/                       \
  --filter pandoc-crossref                                                  \
  --filter pandoc-citeproc                                                  \
  --pdf-engine=xelatex                                                      \
  --top-level-division=section                                              \
  --number-sections                                                         \
  --template $HOME/path/to/your/projects/projectname/controls/robusta.latex \
  ./core/*.md                                                               \
  ./settings/*.yaml                                                         \
  ./metadata/*.yaml
  1. Done!

  2. Alternatively you can omit the long path in the --template option by copying the robusta.latex template located at ./controls/robusta.latex to the default directory of your pandoc templates located at ~/.pandoc/templates/.

  3. If you have copied the robusta.latex template into the directory of your default pandoc templates, then you can execute pandoc like this:

pandoc                                                \
  -s                                                  \
  -o ./output/projectname.pdf                         \
  --data-dir=$HOME/path/to/your/projects/projectname/ \
  --filter pandoc-crossref                            \
  --filter pandoc-citeproc                            \
  --pdf-engine=xelatex                                \
  --top-level-division=chapter                        \
  --number-sections                                   \
  --template robusta.latex                            \
  ./core/*.md                                         \
  ./settings/*.yaml                                   \
  ./metadata/*.yaml
  1. For debugging puproses you can produce a .tex file by runing pandoc with
-o ./output/projectname.tex
  1. Please note, though: the robusta boilerplate is designed to be used with the given directory structure respectively file structure indicated in BODYPLAN.md. Of particular importance are the metadata and settings files: ./metadata/00_01_metadata.yaml ./settings/00_02_settings.yaml.

  2. The boilerplate should work even if you change its inner structure but keep in mind to change all the paths and variables accordingly. The robusta.template file may work as long as you provide some basic variables used in this template file.

Enjoy

  1. Go to ./output/ and enjoy your results.

Other

  1. To read out your current default template execute: pandoc -D latex > default.latex.

License

MIT License

Copyright (c) 2018 Martin Maga

Go to ./LICENSE.md.

References and Credits

  1. Plot graphics: Gnuplot
  2. Blind text: Jasper Van der Jeugt lorem-markdownum
  3. Bug fix by Marco Torchiano @ StackExchange see Pandoc issue 1023.
  4. Atom editor
  5. Better Bib(La)TeX for Zotero
  6. CSL
  7. git
  8. KOMA-Script
  9. LaTeX
  10. Markdown
  11. Pandoc
  12. Pandoc-citeproc
  13. Pandoc-crossref
  14. TeXLive
  15. XeTeX
  16. YAML
  17. Zotero
  18. zotero-citations
  19. zotero-picker
  20. zotfile.

About

A sound and versatile pandoc LaTeX boilerplate to produce academic articles using Markdown files featuring YAML, KOMA-Script, BibLaTeX and CSL

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published