pandoc-df-thesis-template — D. Folio Pandoc thesis template

This repository provides a full featured template for writing a thesis dissertation using Pandoc, http://pandoc.org. Based on an “extended Markdown” sources, this template can deal with many outputs dialect basically supported by Pandoc

• pdf: (preferred) output generated from (pdf/lua)LaTeX;
• html: single (based solely on Pandoc) and multi (based on Jekyll) HTML 5 file, e.g. for web-publications;
• epub: EPUB v3 ebook;
• docbook5: XML/DocBook (v5) and HTML chunked files (currently with limited support);
• odt: LibreOffice/OpenOffice OpenDocument;
• docx: Microsoft Word; etc.

The proposed workflow allows to:

• improve the basic Markdown markup to address the add of macros/command/functions with a particular attention to support acronyms/glossaries (managed with pp)
• manage the figures/images with the proper format for the various output target,
• discover/manage the bibliography files,
• try to build/generate only necessaries files thanks to the dependencies management from the make build process, etc.

Quick Start

Note: Now as a wiki; and documentation have started with a Github-page.

1. Install or check if the following prerequires are available:

   • Pandoc (mandatory) — for converting the Markdown to the output format of your choice.
     • Also recommended: Pandoc-citeproc , Pandoc-crossref
   • PP (mandatory) — A generic Preprocessor (with Pandoc in mind). PP allows to preprocess the “extended Markdown” sources, enabling macros (or commands).
   • A make build system: all the template build workflow relies on the use of a Makefile. Thus, you should have a suitable make software.
   • A LaTeX distribution (e.g. TeXLive, MacTeX…)
     • Also recommended: LuaLateX, BibLatex (with biber), glossaries packages...

2. Recommanded packages:

   • ImageMagick : for image conversion between the different target.

   • Inkscape : to convert SVG images to other image format

     SVG is the recommanded input format for images/pictures of the dissertation contents. It will be then converted/optimized with respect to the considered output target.

   • NPM : for complementary packages (eg. [Bootstrap], JQuery, MathJax, SVGO, etc…) mainly to deal with the HTML target.

   • SASS to facilate the writting of CSS for web-publications. Required if you want to compile CSS for html, epub and docbook targets.

3. Optionally look for the following optional packages:

   • DocBook toolchains: to build document from DocBook this templace use DocBook XSL and thus requires a XSLT (v1) processing tools, such as xsltproc.
   • Jekyll used to generate BUILD_HTML_FORMAT=htmlmulti (e.g. for web-publishing)
     • Thus also recommanded Gem / Bundle to deal with Jekyll plugins
   • SVGO: SVG optimizer for images web-publications.
   • Bootstrap: Build responsive, mobile-first projects on the web

4. Clone the repository on Github in the proper place on your machine, e.g.:

   $ git clone https://github.com/dfolio/pandoc-df-thesis-template.git
   

5. Edit the Makefile (optional), and the _data/variables.yml (advised).

   Note: the basis metadata (title, authors,...) are defined in _data/variables.yml!

6. Once you have written some elements in the sources directory: _md/, with your preferred Markdown editor (e.g. Atom, Sublime…), from the root repository of your dissertation just try running:

   $ make <target>
   

   where <target> is one of the above output dialect (i.e. pdf, html, epub…). Further information about the relevant targets can be shown with the help rule:

   $ make help
   

   provides some help on the other targets.

Further informations on the directories organization are given in the wiki How To? page. The template documentations have started with a Github pages.

Contributes

Feel free (under the CC-By-4.0 terms) to modify/adapt this template for your own purpose (I will appreciate some feedback 👍). To this aim you can:

1. Fork it : go to the pandoc-df-thesis repository and hit the fork button in the upper right corner.
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request with your contributions
6. Please give me your feedbacks or share the template on your social-networks (show the Github pages documentations for this)

For any troubleshooting read, and (eventually) create an issue on pandoc-df-thesis-template GitHub repository.