- 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
sourcedirectory - Step 2: edit the _CONFIG.txt and _SECTIONS.txt files as appropriate (see below)
- Step 3: run make from the command line (
make pdfin linux)(winmake pdfin 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.
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
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-citeprocYou 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 directoryREFS=The name of the bibliography file (.bib) for Pandoc to use. This file should be stored in thesourcedirectory.TEMPLATE=The name of the template file to use from thetemplatesdirectory.DOCX_TEMPLATEandODT_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.texif you want to usewinmake.bat, it must be likeTEMPLATE=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.
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.
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.
The CSL files are located in the csl submodule.
make [targets]
pdf: Produces a PDFhtml: Produce an HTML fileepub: Produce an epub eBookembed: Produce an embedded HTML documentall: Produce all of the aboveclean: Delete the output directory and all of its contentsviewpdf: Automatically open the PDF file generated by thepdftargetviewhtml: Automatically open the HTML file generated by thehtmltarget
Example
make pdf viewpdf
Will generate a PDF and then automatically open it.
Default target: make with no arguments will generate a PDF.
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.
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..
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 2016, 2017 Keith Miyake keith.miyake@gmail.com
Copyright 2011-2016 David Caplan
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/.