# How to Make Zines with LaTeX
The zine was created by converting basic markdown to a PDF using Pandoc/LaTeX. The goal is to document some basics that will hopefully be informative for others who might be interested in also creating nicely-formatted zines from plaintext markdown.

Creating documents in plaintext has a lot of advantages. For one, the files are tiny, making them easy to share, even with very little interent. The content is largely separated from the format, making it easy to search, manipulate, format, and display how you like using whatever tools you want. Markdown can easily be converted to other formats including html, wiki, odt, and pdf. The same markdown file can be converted into a zine, a website, a wiki page, a Powerpoint, or whatever else. Finally, changes to markdown files can be tracked in a git repository (unlike pdfs or Word documents).

## What is LaTeX?
LaTeX is a powerful tool for typesetting professional-looking PDFs. Unlike editors such as Word, where you point and click and drag elements of your document to arrange them to look how you want them to look, LaTeX is a set of instructions about how to arrange your content. You might think of it as being like a programming language for typesetting. The details of how to install and use LaTeX are too much to cover in this zine, but a decent overview can be found here:

[https://www.overleaf.com/learn/latex/Learn_LaTeX_in_30_minutes](https://www.overleaf.com/learn/latex/Learn_LaTeX_in_30_minutes)

One way to use LaTeX is to write your document in a .tex file that contains the instructions for typesetting your document. This requires writing your document in LaTeX syntax (which can be a bit esoteric if you're not familiar). An advantage of writing markdown and then converting it to LaTeX is that your text stays separate from the syntax used by LaTeX.

## What is Pandoc?
Pandoc is a program that converts files from one format to another, such as converting markdown to html. It can even convert files to PDFs directly (it uses LaTeX for this). Creating a PDF with pandoc is simple:

    pandoc zine.md -o zine.pdf

Converting markdown to a pdf in this way creates a _standalone_ document, in which pandoc makes several typesetting decisions for you. After running this command you will have a pdf containing the content of your .md file, including formatted headings, bold and italics, links, tables, footnotes, code with syntax highlighting, and more. However, these default styles look more like an academic paper than a cool zine.

Pandoc can also generate document _fragments_, without any of these decisions being made. The advantage of this approach is that *you* control the styling. The disadvantage of this approach is that *you* control the styling. You will need to convert the markdown file to the intermediate .tex format and give LaTeX some instructions on how to render your document. Fortunately, you can get some pretty good results with just some basics, covered below.

To generate a fragment: `pandoc zine.md -o zine.tex`

##  How to Make the Zine

To begin you will need two documents: A .md file with your content, and a .tex file with your LaTeX instrutcions. The basic strucutre of a LaTeX file is:

```tex
\documentclass{your-class-here}

% <package imports and customizations go here>

\begin{document}

% <content goes here>

\end{document}

```

But instead of containing the document content it will `\input{your-markdown-file.tex}` where _your-markdown-file.tex_ was generated by Pandoc from _your-markdown-file.md_.

### Document Class
This project implements a custom _zine_ class, which implements the _book_ document class (since it's already prepared to structure a two-page document) with a few customizations:

- Sets the page size to 8.5in x 5.5in (an A4 page folded in half)
- Adds an image and a title to the front cover
- Adds a logo and _printed by <author>_ to the back cover
- A few various style decisions (e.g., removing styling from links)

This essentially just moves the preamble out of the main .tex document and into a separate class file, so _main.tex_ includes only the commands relevant to the zine content.

### Necessary Packages

This zine uses the following classes:

- graphicx: for adding images
- parskip:  adds space between paragraphs
- fancyhdr: controls headers and footers
- titlesec: controls section formatting (headings)
- hyperref: deals with the links that pandoc adds (links don't show in zines but latex complains)
- listings: for code syntax highlighting (not relevant for most zines)

### Generating the Output

Simply run:

```bash
pandoc doc.md -o doc.tex
pdflatex -interaction=nonstopmode doc.tex
```

This generates a PDF of the zine.

### Printing Considerations

When printed, the page-order of a zine can be somewhat unintuitive. When printing and folding the cover, for example, the first page of the zine is next to the last page, and on the back the second-to-last is next to the second.

![booklet layout](./public/page-order.jpg)

Some print dialogues will handle this for you (known as _booklet format_). This can also be accomplished using pdfbook2, but first we need to make sure the total page number of the zine is a multiple of 4 (since one paper leaf contains four zine pages).

This zine also has a blank page after the front cover and before the back cover for the printed version, so that the back side of each cover is blank:

```bash
#calculate pages to extract first and last for cover
pages=$(pdfinfo main.pdf | awk '/^Pages:/ {print $2}')

# split cover from guts to add correct signature
pdfjam main.pdf 1,$(($pages))-$pages -o cover.pdf
pdfjam main.pdf 2-$((pages-1)) -o guts.pdf

# insert blank pages after front cover and before back cover
pdfjam cover.pdf '1,{},{},2' --outfile cover.pdf

# calculate pages for guts signature length
pages=$(pdfinfo guts.pdf | awk '/^Pages:/ {print $2}')
let rem=pages%4
let extra=$((4-rem))%4
let sig=pages+extra

# booklet print
pdfbook2 -n --short-edge cover.pdf
pdfbook2 -n --signature=$sig --short-edge guts.pdf

# put them back together!
pdfunite cover-book.pdf guts-book.pdf print-zine.pdf
mv main.pdf read-zine.pdf
```

And now you have a zine both for reading online and printing!

## markdown demo

### Headings
# H1 Here is a level one heading
## H2 Here is a level two heading
### H3 Here is a level three heading

### bold text
Here is what **bold text** looks like.

### italicized text
Here is what *italicized text* looks like.

### blockquote
Block quotes look like this:

> Donec vitae enim non purus consequat sollicitudin sed id sapien. Praesent vehicula iaculis mollis. Nam sodales condimentum mi, non gravida felis mattis quis. Phasellus mattis faucibus elit, sit amet elementum leo malesuada eget. Morbi porta eleifend eros eget cursus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras sit amet enim eget arcu pretium egestas. Sed sit amet elit arcu. In hac habitasse platea dictumst.

### ordered list
1. First item
2. Second item
3. Third item

### unordered list
- First item
- Second item
- Third item

### code

Pandoc implements bacticks as `\texttt{}`:

`sudo rm -rf *`

It implements indentation as `verbatim`:

    sudo rm -rf *

And it has the ability to implement code blocks with syntax highlighting (more on this later):

```go
package main

import "fmt"

func main() {
    fmt.Println("hello world")
}
```
### horizontal rule

Praesent elit lacus, feugiat accumsan augue quis, tristique ultrices est. Curabitur in aliquet magna, a commodo nulla. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.

---

Maecenas ultricies, mi non pretium porta, ex ante ultrices justo, a pulvinar sapien libero sed leo. Duis non pulvinar ex, tempus tempor velit. In id justo a velit semper dignissim. Cras at mauris purus.

### link

Click [here](https://example.com) to visit a website on the internet.

### image

![somebody's gotta keep it punk, like chaos, man!](./public/chaos.png)

### table

Tables are easy to implement in markdown, and they end up looking decent:


| Status      | Description |
| ----------- | ----------- |
| Header      | Title       |
| Paragraph   | Text        |

### footnote

[Footnotes](Footnotes) are an impressive feature of markdown! Identifiers can be numbers or words, but they can’t contain spaces or tabs. Identifiers only correlate the footnote reference with the footnote itself — in the output, footnotes are numbered sequentially.

Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

    Add as many paragraphs as you like.

This sentence follows the second footnote but won't be included because it's not indented.

Note: Not sure about GitHub, but Gogs markdown does not implement footnotes correctly! However, they are implemented correctly in LaTeX and HTML.

### heading id

#### My Great Heading {#custom-id}
(see below for link to this heading)


### definition list

term
: definition

### strikethrough

~~strikethrough~~

### task list

- [ ] incomplete item
- [x] complete item

## syntax highlighting

Pandoc implements it's own syntax highlighting using a Haskel package (skylighting).

To implement syntax highlighting in LaTeX we can use the  [listings](https://ctan.org/pkg/listings?lang=en) package by passing the `--listings` argument to pandoc and adding the following to our .tex preamble:

```tex
\usepackage{listings}
\lstset{ %
  backgroundcolor=\color{white},   % choose the background color
  basicstyle=\footnotesize,        % size of fonts used for the code
  breaklines=true,                 % automatic line breaking only at whitespace
  captionpos=b,                    % sets the caption-position to bottom
  commentstyle=\color{mygreen},    % comment style
  escapeinside={\%*}{*)},          % if you want to add LaTeX within your code
  keywordstyle=\color{blue},       % keyword style
  stringstyle=\color{mymauve},     % string literal style
}
```
There is also a way to use `minted` for syntax highlighting, however it has several issues:

- minted requires Pygments
- minted requires you to run pdflatex with `--shell-escape` (yikes!)
- minted requires an external [pandoc-filter](https://pandoc.org/lua-filters.html).
  - To use, download [here](https://github.com/pandoc/lua-filters/blob/master/minted/minted.lua), then run by passing `--filter minted.lua` to pandoc.
- minted adds a new directory to your project directory (and many lines to the log output).
- To use `breakspace=true` you have to add additional metadata to the .md file (ew!)

So in short, stay away from minted and use listings!