Skip to content

dfolio/pandoc-df-thesis-template

Repository files navigation

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

Travis Build Status License Version contributions welcome

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

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:

  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)
    • 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.