Skip to content

Commit 96b75f3

Browse files
instantiatorinstantiator
committed
Initial commit
0 parents  commit 96b75f3

23 files changed

Lines changed: 1216 additions & 0 deletions

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.vscode
2+
source/build
3+
.DS_Store

‎Dockerfile‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
FROM pandoc/latex
2+
3+
RUN apk update && apk upgrade
4+
RUN apk add bash
5+
RUN apk add poppler-utils
6+
7+
COPY scripts/build.sh /build.sh
8+
9+
ENTRYPOINT [ "/build.sh" ]

‎README.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Template thesis
2+
3+
> The things I'll do to avoid learning LaTeX.
4+
5+
This is a template for building a thesis PDF that's written in markdown, using features and styles from LaTeX.
6+
7+
* Runs in a Docker container for portability.
8+
* Includes support for a cover page (not numbered).
9+
* Includes support for building a table of contents.
10+
* Numbers the various main sections of the document.
11+
* Includes support for LaTeX mathematics / formulae.
12+
* Includes support for citations, and a BibTex bibliography.
13+
14+
The document is built using a Docker container that contains everything it needs.
15+
16+
## Prerequisites
17+
18+
The build takes place in a [Docker](https://www.docker.com/) container.
19+
20+
Instructions for installing Docker are available below for OS X. Feel free to submit a PR with extra information for other systems.
21+
22+
### OS X
23+
24+
On OS X, you can install Docker Desktop using [homebrew](https://brew.sh/).
25+
26+
1. Install homebrew:
27+
28+
```bash
29+
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
30+
```
31+
32+
2. Install docker:
33+
34+
```bash
35+
brew install --cask docker
36+
```
37+
38+
## Building your document
39+
40+
Build the document with the `build-project.sh` script:
41+
42+
```bash
43+
./build-project.sh
44+
```
45+
46+
On its first run, Docker will attempt to build the container before executing the build script that then converts your markdown to a single PDF document.
47+
48+
The final line of a successful build indicates where to find the final output PDF:
49+
50+
```text
51+
Output document: source/build/Sample-Project_Your-Name.pdf
52+
```
53+
54+
## Source files
55+
56+
Place your source files in the `source/` directory. The build script expects to find:
57+
58+
* `00-cover.md` - the cover page.
59+
* Files with prefix `01` to `08` - the main sections of your thesis.
60+
* `bibliography.bib` - a BibTex bibliography.
61+
62+
NB. See sample files `05-XX-*` for an example of how to split out a large section into smaller files to make them a little easier to edit.
63+
64+
If your structure requires more or fewer sections, edit `scripts/build.sh`, and modify the `for I` loop.
65+
66+
## Footnotes
67+
68+
Refer to your footnote with `[^1]` and provide the text of it anywhere in the document as:
69+
70+
```text
71+
[^1]: this is the text
72+
```
73+
74+
## Citations
75+
76+
`bibliography.bib` is a BibTex file containing your references.
77+
78+
An easy way to obtain BibTex reference information is to search for the reference on Google Scholar. You can then obtain a BibTex reference using the `"` symbol beneath your chosen search result.
79+
80+
To refer to something in your bibliography, use `@`-notation, and refer to the name of the entry in your bibliography, eg.
81+
82+
```text
83+
this paper about Paralysis Proofs @ParalysisProofs
84+
```
85+
86+
You can also modify your references, eg.
87+
88+
* `@Something`
89+
* `@Something [p. 45]`
90+
* `@Something [p. 45, and a suffix]`
91+
* `@Something [see also @SomethingElse]`
92+
93+
### Citation styles
94+
95+
Citations are styled according to `source/util/citation-style.csl`. You can see by inspection that this is a minor modification to `oxford-university-press-scimed-numerical.csl`, also in that directory.
96+
97+
CSL styles are available at the GitHub repository: [citation-style-language/styles](https://github.com/citation-style-language/styles)
98+
99+
The [Zotero Style Repository](https://www.zotero.org/styles) is a nice facility to help you find, preview, and download different citation styles.
100+
101+
## Formulae
102+
103+
The build script invokes `pandoc` with the `markdown+tex_math_dollars` option - which interprets LaTeX formulae surrounded by `$` signs. There should be no space after the opening `$` and no space before the closing `$`. eg.
104+
105+
```latex
106+
$C_K = K + a^{2^t} \mod{n}$
107+
```
108+
109+
There are plenty of resources for writing LaTeX formulae online. I found [LaTeX/Mathematics](https://en.wikibooks.org/wiki/LaTeX/Mathematics) quite helpful.
110+
111+
## Figures
112+
113+
To include a figure in your document, provide it as a Markdown image. The alternative text will be used as the figure's description, eg.
114+
115+
```text
116+
![Here is an aperture icon](resources/aperture.png)
117+
```
118+
119+
(This aperture icon comes from [Google Fonts](https://fonts.google.com/icons?icon.query=aperture).)
120+
121+
If you do not provide alternative text, the image will be included but not as a figure (as seen in the cover page).
122+
123+
To adjust the size of your image, you can provide some information in a suffix to the image markdown, eg. `{ width=100px }`
124+
125+
## The build script
126+
127+
The docker image contains `build.sh` from `scripts/build.sh`. It's a `bash` script that does the following things:
128+
129+
* Clears out any previous output in `source/build`.
130+
* Prepares the cover page markdown with a following page-break.
131+
* Prepares the main document markdown by combining the additional sections, separated by page-breaks.
132+
* Converts the cover page to a PDF, using `pandoc`.
133+
* Converts the main document to a PDF, using `pandoc`.
134+
* Numbers the sections.
135+
* Prefixes a table of contents.
136+
* Builds formulae using tex math.
137+
* Builds and appends citations from the bibliography.
138+
* Combines the cover page and main document using `pdfunite`.
139+
* Prints word counts from each section.
140+
* Prints the location of the final document PDF in `source/build`.
141+
142+
Outputs from the script are found in: `source/build`
143+
144+
NB. The script expects to find section 00 (the cover), and sections 01 to 08 (for each of the main sections). If diverging from this structure, you may need to alter the main `for I` loop in the script.
145+
146+
## Troubleshooting
147+
148+
**Pandoc may crash without a very meaningful error.** This could indicate that you have not assigned enough memory for Docker containers. Try increasing this assignment in Docker Desktop's Preferences / Resources page.
149+
150+
## Contributing
151+
152+
If you've an improvement or modification, please submit a PR.
153+
154+
If you have any issues or suggestions, please create an issue.
155+
156+
Feel free to fork, improve, modify, or do whatever you please with this repository.

‎build-project.sh‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
#!/bin/sh
2+
3+
docker build . -t instantiator/project-builder
4+
docker run --rm --volume "`pwd`/source:/source" instantiator/project-builder

‎scripts/build.sh‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
#!/bin/bash
2+
3+
set -e
4+
set -o pipefail
5+
6+
# constants
7+
THESIS_DOCUMENT_ROOT=Sample-Project_Your-Name
8+
THESIS_COVER_ROOT=cover
9+
BIBLIOGRAPHY=bibliography.bib
10+
CITATION_STYLE=citation-style.csl
11+
LATEX_TEMPLATE=util/template.latex
12+
13+
# enter source directory
14+
pushd /source
15+
16+
# clear outputs
17+
mkdir -p build
18+
rm -rf build/* || true
19+
20+
# create the cover page markdown
21+
cat 00*.md >> build/$THESIS_COVER_ROOT.md
22+
cat 00*.md >> build/$THESIS_COVER_ROOT.formatted.md
23+
cat util/pagebreak.md >> build/$THESIS_COVER_ROOT.formatted.md
24+
25+
# append each section to the thesis markdown
26+
for I in 0{1..8}; do
27+
cat util/blank.md >> build/$THESIS_DOCUMENT_ROOT.md
28+
cat util/pagebreak.md >> build/$THESIS_DOCUMENT_ROOT.formatted.md
29+
30+
for FILENAME in `ls $I*.md | sort`; do
31+
# FILENAME=$I*.md
32+
cat $FILENAME >> build/$THESIS_DOCUMENT_ROOT.md
33+
cat $FILENAME >> build/$THESIS_DOCUMENT_ROOT.formatted.md
34+
done
35+
done
36+
37+
# convert cover to PDF
38+
pandoc \
39+
build/$THESIS_COVER_ROOT.formatted.md \
40+
-o build/$THESIS_DOCUMENT_ROOT.cover.pdf
41+
42+
# convert thesis to PDF
43+
pandoc \
44+
--standalone \
45+
--number-sections \
46+
--table-of-contents \
47+
-f markdown+tex_math_dollars \
48+
--template=$LATEX_TEMPLATE \
49+
--citeproc \
50+
--csl=util/$CITATION_STYLE \
51+
--bibliography=$BIBLIOGRAPHY \
52+
build/$THESIS_DOCUMENT_ROOT.formatted.md \
53+
-o build/$THESIS_DOCUMENT_ROOT.body.pdf
54+
55+
# combine cover and thesis into main document
56+
pdfunite \
57+
build/$THESIS_DOCUMENT_ROOT.cover.pdf \
58+
build/$THESIS_DOCUMENT_ROOT.body.pdf \
59+
build/$THESIS_DOCUMENT_ROOT.pdf
60+
61+
# return to initial directory
62+
popd
63+
64+
# describe output
65+
echo "Word counts:"
66+
wc -w /source/*.md
67+
echo "Output document: source/build/$THESIS_DOCUMENT_ROOT.pdf"

‎source/00-cover.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
\pagenumbering{gobble}
2+
3+
# Thesis Title {-}
4+
5+
![](resources/aperture.png){ width=100px }
6+
7+
First name Surname
8+
9+
Department
10+
11+
Institution

‎source/01-introduction.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Introduction
2+
3+
This project hopes to answer the following question:
4+
5+
* Can I write up my work using Markdown, but benefit from the features of LaTeX?

‎source/02-background.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Background
2+
3+
## Assumptions
4+
5+
* Users of this project don't wish to learn much (or any) LaTeX, and have some familiarity with Markdown.
6+
* Users of this project have access to a computer that can run Docker.
7+
8+
### Scope
9+
10+
This project provides a framework for writing Markdown, to convert it to PDF in the style of a LaTeX document.
11+
12+
Certain common tasks have been included in the scope:
13+
14+
* Support for LaTeX (tex math) formulae.
15+
* Numbering of sections.
16+
* Prepending a cover page.
17+
* Prepending a table of contents.
18+
* Appending a bibliography for citations.
19+
20+
Determining the best structure for your project, or the content you should include in your write-up is left as an exercise for the reader.

‎source/03-related-work.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Related work
2+
3+
This project builds on the shoulders of the various [pandoc docker images](https://github.com/pandoc/dockerfiles#available-images).
4+

‎source/04-methodology.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Methodology
2+
3+
## Footnotes
4+
5+
It's easy to write a footnote[^1].
6+
7+
[^1]: Indicate your footnote with `[^1]` and provide the text of it close by using `[^1]: this is the text`
8+
9+
## Citations
10+
11+
Cite your bibliography using @-notation. For example, you could refer to this paper about Paralysis Proofs @ParalysisProofs.
12+
13+
## Formulae
14+
15+
As described in `README.md` you can write LaTeX formulae by surrounding them with `$` signs, eg.
16+
17+
$C_K = K + a^{2^t} \mod{n}$
18+
19+
NB. There should be no space after the opening `$` and no space before the closing `$`.
20+
21+
## Figures
22+
23+
To include a figure in your document, provide it as a Markdown image. The alternative text will be used as the figure's description, eg.
24+
25+
![Here is an aperture icon](resources/aperture.png){ width=100px }
26+
27+
If you do not provide alternative text, the image will be included but not as a figure.
28+
29+
To adjust the size of your image, you can provide some information in a suffix to the image markdown, eg. `{ width=100px }`

0 commit comments

Comments
 (0)