Awesome

Pandoc Markdown-Latex Boilerplate

Forked from earlier work by:
- Initial Author: David Caplan http://www.davecap.com/
- Extended Author: Brian Khuu http://www.briankhuu.com/

Use this to write a paper in Markdown and render it using the Pandoc engine.

Step 0: clone or fork this repository
Step 1: write your document(s) using Pandoc Markdown and save them in the source directory
Step 2: edit the _CONFIG.txt and _SECTIONS.txt files as appropriate (see below)
Step 3: run make from the command line (make pdf in linux)(winmake pdf in windows)
Step 4: enjoy pdf

QUICKSTART for windows users: double-click on winmake.bat

NOTE: The windows batch file hasn't been fully tested, but is based on the previously working version published by David Caplan. Testing and pull requests are welcome.

Requirements

Follow instruction on installing pandoc in this link http://pandoc.org/installing.html . For PDF output, you’ll also need to install LaTeX. We recommend MiKTeX.

You also need to install the content of https://github.com/citation-style-language/styles into the csl if you want to fully ultilize csl. You can update them as follows:

$ git submodule update

Building

Configuring the build system

Edit the configuration file _CONFIG.txt, which contains the following defaults:

BUILDNAME=dissertation
OUTPUT_FOLDER=output
REFS=references.bib
TEMPLATE=cuny
DOCX_TEMPLATE=
ODT_TEMPLATE=
CSL=chicago-author-date
PANDOC_OPTIONS=--dpi=600 --latex-engine=xelatex --filter pandoc-tablenos --filter pandoc-fignos --filter pandoc-citeproc

You can customize the configuration variables as follows:

BUILDNAME= Set the name of the output file (e.g., dissertation.pdf)
OUTPUT_FOLDER= Set the name of the output folder within the current directory
REFS= The name of the bibliography file (.bib) for Pandoc to use. This file should be stored in the source directory.
TEMPLATE= The name of the template file to use from the templates directory.
DOCX_TEMPLATE and ODT_TEMPLATE= If you want to output to a .docx or .odt file, be sure that you have a template document with the appropriate extension (e.g., cuny.docx)
CSL= Choose from a list of Citation Style Language files found in ./csl/ e.g. IEEE style.
PANDOC_OPTIONS= Options to pass directly to Pandoc. See the Pandoc documentation for more information. By default, this script includes the pandoc-tablenos, pandoc-fignos, and pandoc-citeproc filters.

Notes:

# are comments.
You cannot have spaces in your key=value like TEMPLATE = ut-thesis.tex if you want to use winmake.bat, it must be like TEMPLATE=ut-thesis.tex.
If you open the _CONFIG.txt file to modify it (e.g. notepad.exe), you need to close the config file, otherwise MikTex will come up with an error stating that the files are already in use.

SECTIONS_FILEPATH

Edit the source file _SECTIONS.txt, which contains a list of all of the files to include:

    metadata.yml
    chapter1.md
    chapter2.md
    appendix_a.md
    references.md

Where each file to be included is entered on a single line or separated by a single space.

The first item should be your Pandoc metadata file (e.g., metadata.yml), which contains the information to be included in the front and back matter, such as Title, Author, committee members, abstract, etc., as well as formatting options.

The last item should be the references (or bibliography, works cited) document (e.g., references.md). This is a special file with formatting instructions written in LaTex. You can customize the formatting using your own LaTex styles for things like hanging indents, but the contents of the bibliography are generated automatically from your text and references file (references.bib). See the Pandoc documentation for more information.

Metadata

Be sure to edit the metadata.yml file in the source directory. See the Pandoc documentation for more information, and refer to the cuny.tex template to see what some of the options do.

CSL: Citation Style Language

The CSL files are located in the csl submodule.

Linux/OS X

make [targets]

Optional targets

pdf: Produces a PDF
html: Produce an HTML file
epub: Produce an epub eBook
embed: Produce an embedded HTML document
all: Produce all of the above
clean: Delete the output directory and all of its contents
viewpdf: Automatically open the PDF file generated by the pdf target
viewhtml: Automatically open the HTML file generated by the html target

Example

make pdf viewpdf

Will generate a PDF and then automatically open it.

Default target: make with no arguments will generate a PDF.

Windows

Just double click on winmake.bat and type pdf or pdf-safemode if pdf doesn't work. Else choose html.

winmake clean

Removes the build folder

winmake pdf

Builds a pdf file to ./build/ folder. Requires LaTeX.

winmake pdf-safemode

Builds a pdf file to ./build/ folder. Requires LaTeX. Ignores template and CSL settings.

winmake epub

Builds a epub file to ./build/ folder

winmake html

Builds a html file to ./build/ folder

winmake

Opens up a prompt.

Tips and Tricks

Using makefile in windows

You are not restricted to using winmake.bat in windows. If you install git for windows from http://www.git-scm.com/ in addition to the make program in http://gnuwin32.sourceforge.net/packages/make.htm (Also add the program to path). This is since a copy of git will include a Git Bash Shell, which will support unix commands like cat etc... .

For your convenience, a copy of make.exe (As of 25 November 2006) is included. Being GPLed its source code is also in the website..

Opening Window commandline in the right directory quickly

SHIFT+RIGHT_CLICK on your folder in windows will display an extra entry in the dropdown saying "Open Command Window Here". This will save you lots of time. Or you can make a batch file like buildpdf.bat that contains winmake pdf.

COPYRIGHT

LICENSE

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.