Initial commit
This commit is contained in:
Zhongwei Li
579
skills/pandoc/references/yaml_reference.md
Normal file
579
skills/pandoc/references/yaml_reference.md
Normal file
@@ -0,0 +1,579 @@
|
||||
# Pandoc YAML Variables Reference
|
||||
|
||||
Comprehensive guide to YAML frontmatter variables for Pandoc document conversion.
|
||||
|
||||
## Core Metadata
|
||||
|
||||
### title
|
||||
**Type:** String
|
||||
**Usage:** Document title
|
||||
**Example:**
|
||||
```yaml
|
||||
title: "My Research Paper"
|
||||
```
|
||||
|
||||
### author
|
||||
**Type:** String or List
|
||||
**Usage:** Author name(s)
|
||||
**Examples:**
|
||||
```yaml
|
||||
author: "John Smith"
|
||||
|
||||
# Multiple authors
|
||||
author:
|
||||
- "John Smith"
|
||||
- "Jane Doe"
|
||||
```
|
||||
|
||||
### date
|
||||
**Type:** String
|
||||
**Usage:** Publication/document date
|
||||
**Examples:**
|
||||
```yaml
|
||||
date: "November 2024"
|
||||
date: "2024-11-16"
|
||||
date: "16 November 2024"
|
||||
```
|
||||
|
||||
### lang
|
||||
**Type:** String (BCP 47 language code)
|
||||
**Usage:** Document language for hyphenation, quotes, citations
|
||||
**Examples:**
|
||||
```yaml
|
||||
lang: en-GB # British English
|
||||
lang: en-US # American English
|
||||
lang: en-IE # Irish English
|
||||
lang: de # German
|
||||
lang: fr # French
|
||||
```
|
||||
|
||||
## Bibliography and Citations
|
||||
|
||||
### bibliography
|
||||
**Type:** String or List
|
||||
**Usage:** Path to BibTeX (.bib) file(s)
|
||||
**Examples:**
|
||||
```yaml
|
||||
bibliography: references.bib
|
||||
|
||||
# Multiple files
|
||||
bibliography:
|
||||
- references.bib
|
||||
- additional.bib
|
||||
```
|
||||
|
||||
### csl
|
||||
**Type:** String
|
||||
**Usage:** Path to Citation Style Language (.csl) file
|
||||
**Examples:**
|
||||
```yaml
|
||||
csl: harvard.csl
|
||||
csl: apa.csl
|
||||
csl: ieee.csl
|
||||
```
|
||||
|
||||
**Download CSL styles:** https://github.com/citation-style-language/styles
|
||||
|
||||
### link-citations
|
||||
**Type:** Boolean
|
||||
**Usage:** Make citations clickable links to bibliography
|
||||
**Example:**
|
||||
```yaml
|
||||
link-citations: true
|
||||
```
|
||||
|
||||
### citeproc
|
||||
**Type:** Boolean (command-line option, not frontmatter)
|
||||
**Usage:** Enable citation processing
|
||||
**Command:**
|
||||
```bash
|
||||
pandoc doc.md -o doc.pdf --citeproc
|
||||
```
|
||||
|
||||
## PDF Output Settings
|
||||
|
||||
### documentclass
|
||||
**Type:** String
|
||||
**Usage:** LaTeX document class
|
||||
**Options:**
|
||||
- `article` - Short documents, papers
|
||||
- `report` - Longer documents with chapters
|
||||
- `book` - Books with front matter
|
||||
- `beamer` - Presentations
|
||||
|
||||
**Example:**
|
||||
```yaml
|
||||
documentclass: report
|
||||
```
|
||||
|
||||
### fontsize
|
||||
**Type:** String
|
||||
**Usage:** Base font size
|
||||
**Options:** `10pt`, `11pt`, `12pt`
|
||||
**Example:**
|
||||
```yaml
|
||||
fontsize: 12pt
|
||||
```
|
||||
|
||||
### geometry
|
||||
**Type:** String
|
||||
**Usage:** Page layout and margins
|
||||
**Examples:**
|
||||
```yaml
|
||||
geometry: margin=1in
|
||||
geometry: margin=2cm
|
||||
geometry: "left=1.5in, right=1in, top=1in, bottom=1in"
|
||||
geometry: "a4paper, margin=2.5cm"
|
||||
```
|
||||
|
||||
### linestretch
|
||||
**Type:** Number
|
||||
**Usage:** Line spacing multiplier
|
||||
**Examples:**
|
||||
```yaml
|
||||
linestretch: 1.0 # Single spacing
|
||||
linestretch: 1.5 # 1.5 spacing
|
||||
linestretch: 2.0 # Double spacing
|
||||
```
|
||||
|
||||
### papersize
|
||||
**Type:** String
|
||||
**Usage:** Paper size
|
||||
**Options:** `a4`, `letter`, `legal`, `executive`
|
||||
**Example:**
|
||||
```yaml
|
||||
papersize: a4
|
||||
```
|
||||
|
||||
## Table of Contents
|
||||
|
||||
### toc
|
||||
**Type:** Boolean
|
||||
**Usage:** Include table of contents
|
||||
**Example:**
|
||||
```yaml
|
||||
toc: true
|
||||
```
|
||||
|
||||
### toc-depth
|
||||
**Type:** Integer (1-5)
|
||||
**Usage:** Maximum heading level in TOC
|
||||
**Example:**
|
||||
```yaml
|
||||
toc-depth: 3 # Include h1, h2, h3
|
||||
```
|
||||
|
||||
### toc-title
|
||||
**Type:** String
|
||||
**Usage:** Custom TOC heading
|
||||
**Example:**
|
||||
```yaml
|
||||
toc-title: "Contents"
|
||||
```
|
||||
|
||||
### lof
|
||||
**Type:** Boolean
|
||||
**Usage:** Include list of figures
|
||||
**Example:**
|
||||
```yaml
|
||||
lof: true
|
||||
```
|
||||
|
||||
### lot
|
||||
**Type:** Boolean
|
||||
**Usage:** Include list of tables
|
||||
**Example:**
|
||||
```yaml
|
||||
lot: true
|
||||
```
|
||||
|
||||
## Section Numbering
|
||||
|
||||
### numbersections
|
||||
**Type:** Boolean
|
||||
**Usage:** Number section headings automatically
|
||||
**Example:**
|
||||
```yaml
|
||||
numbersections: true
|
||||
```
|
||||
|
||||
### secnumdepth
|
||||
**Type:** Integer
|
||||
**Usage:** Maximum heading level to number
|
||||
**Example:**
|
||||
```yaml
|
||||
secnumdepth: 3 # Number up to h3
|
||||
```
|
||||
|
||||
## LaTeX Customization
|
||||
|
||||
### header-includes
|
||||
**Type:** String (multiline)
|
||||
**Usage:** Custom LaTeX commands and packages
|
||||
**Example:**
|
||||
```yaml
|
||||
header-includes: |
|
||||
\usepackage{graphicx}
|
||||
\usepackage{float}
|
||||
\usepackage{hyperref}
|
||||
\usepackage{amsmath}
|
||||
```
|
||||
|
||||
### include-before
|
||||
**Type:** String (multiline)
|
||||
**Usage:** Content before document body
|
||||
**Example:**
|
||||
```yaml
|
||||
include-before: |
|
||||
\begin{abstract}
|
||||
This is the abstract.
|
||||
\end{abstract}
|
||||
```
|
||||
|
||||
### include-after
|
||||
**Type:** String (multiline)
|
||||
**Usage:** Content after document body
|
||||
**Example:**
|
||||
```yaml
|
||||
include-after: |
|
||||
\appendix
|
||||
# Appendix content
|
||||
```
|
||||
|
||||
## Typography
|
||||
|
||||
### mainfont
|
||||
**Type:** String
|
||||
**Usage:** Main document font (requires XeLaTeX or LuaLaTeX)
|
||||
**Example:**
|
||||
```yaml
|
||||
mainfont: "Times New Roman"
|
||||
```
|
||||
|
||||
### sansfont
|
||||
**Type:** String
|
||||
**Usage:** Sans-serif font
|
||||
**Example:**
|
||||
```yaml
|
||||
sansfont: "Arial"
|
||||
```
|
||||
|
||||
### monofont
|
||||
**Type:** String
|
||||
**Usage:** Monospace font for code
|
||||
**Example:**
|
||||
```yaml
|
||||
monofont: "Courier New"
|
||||
```
|
||||
|
||||
### fontfamily
|
||||
**Type:** String
|
||||
**Usage:** LaTeX font package
|
||||
**Example:**
|
||||
```yaml
|
||||
fontfamily: palatino
|
||||
```
|
||||
|
||||
## Presentation (Beamer)
|
||||
|
||||
### theme
|
||||
**Type:** String
|
||||
**Usage:** Beamer theme
|
||||
**Options:** Madrid, Berlin, Copenhagen, Dresden, Frankfurt, Singapore, Warsaw
|
||||
**Example:**
|
||||
```yaml
|
||||
theme: Madrid
|
||||
```
|
||||
|
||||
### colortheme
|
||||
**Type:** String
|
||||
**Usage:** Beamer color scheme
|
||||
**Options:** default, dolphin, beaver, crane, seahorse
|
||||
**Example:**
|
||||
```yaml
|
||||
colortheme: default
|
||||
```
|
||||
|
||||
### fonttheme
|
||||
**Type:** String
|
||||
**Usage:** Beamer font theme
|
||||
**Options:** default, serif, structurebold, structureitalicserif
|
||||
**Example:**
|
||||
```yaml
|
||||
fonttheme: default
|
||||
```
|
||||
|
||||
### aspectratio
|
||||
**Type:** Integer
|
||||
**Usage:** Slide aspect ratio
|
||||
**Options:** `43` (4:3), `169` (16:9), `1610` (16:10)
|
||||
**Example:**
|
||||
```yaml
|
||||
aspectratio: 169
|
||||
```
|
||||
|
||||
### navigation
|
||||
**Type:** String
|
||||
**Usage:** Navigation symbols
|
||||
**Options:** horizontal, vertical, frame
|
||||
**Example:**
|
||||
```yaml
|
||||
navigation: horizontal
|
||||
```
|
||||
|
||||
## HTML Output
|
||||
|
||||
### css
|
||||
**Type:** String or List
|
||||
**Usage:** CSS stylesheet path(s)
|
||||
**Examples:**
|
||||
```yaml
|
||||
css: style.css
|
||||
|
||||
# Multiple stylesheets
|
||||
css:
|
||||
- style.css
|
||||
- syntax.css
|
||||
```
|
||||
|
||||
### self-contained
|
||||
**Type:** Boolean (command-line)
|
||||
**Usage:** Embed all resources in HTML
|
||||
**Command:**
|
||||
```bash
|
||||
pandoc doc.md -o doc.html --self-contained
|
||||
```
|
||||
|
||||
## Code Highlighting
|
||||
|
||||
### highlight-style
|
||||
**Type:** String
|
||||
**Usage:** Syntax highlighting theme
|
||||
**Options:** tango, pygments, kate, monochrome, espresso, zenburn, haddock, breezedark
|
||||
**Example:**
|
||||
```yaml
|
||||
highlight-style: tango
|
||||
```
|
||||
|
||||
## Custom Variables
|
||||
|
||||
### Custom Title Page Fields
|
||||
|
||||
**For thesis/academic work:**
|
||||
```yaml
|
||||
supervisor: "Dr. Jane Smith"
|
||||
institution: "University Name"
|
||||
department: "Department of Computer Science"
|
||||
degree: "BSc Computer Science"
|
||||
```
|
||||
|
||||
**Student Information:**
|
||||
```yaml
|
||||
student-id: "C21348423"
|
||||
programme: "TU856"
|
||||
module: "COMP4060"
|
||||
```
|
||||
|
||||
**Contact Information:**
|
||||
```yaml
|
||||
email: "student@example.com"
|
||||
website: "https://example.com"
|
||||
```
|
||||
|
||||
## BibTeX Reference
|
||||
|
||||
### Entry Types
|
||||
|
||||
**Article:**
|
||||
```bibtex
|
||||
@article{citekey,
|
||||
author = {Smith, John and Doe, Jane},
|
||||
title = {Paper Title},
|
||||
journal = {Journal Name},
|
||||
year = {2024},
|
||||
volume = {42},
|
||||
number = {3},
|
||||
pages = {123--145},
|
||||
doi = {10.1234/example}
|
||||
}
|
||||
```
|
||||
|
||||
**Book:**
|
||||
```bibtex
|
||||
@book{citekey,
|
||||
author = {Johnson, Alice},
|
||||
title = {Book Title},
|
||||
publisher = {Publisher Name},
|
||||
year = {2023},
|
||||
edition = {2nd},
|
||||
address = {City},
|
||||
isbn = {978-0-12-345678-9}
|
||||
}
|
||||
```
|
||||
|
||||
**Conference Paper:**
|
||||
```bibtex
|
||||
@inproceedings{citekey,
|
||||
author = {Brown, Robert},
|
||||
title = {Paper Title},
|
||||
booktitle = {Conference Proceedings},
|
||||
year = {2024},
|
||||
pages = {45--52},
|
||||
publisher = {ACM},
|
||||
doi = {10.1145/example}
|
||||
}
|
||||
```
|
||||
|
||||
**PhD Thesis:**
|
||||
```bibtex
|
||||
@phdthesis{citekey,
|
||||
author = {Williams, Michael},
|
||||
title = {Thesis Title},
|
||||
school = {University Name},
|
||||
year = {2023},
|
||||
address = {City, Country}
|
||||
}
|
||||
```
|
||||
|
||||
**Master's Thesis:**
|
||||
```bibtex
|
||||
@mastersthesis{citekey,
|
||||
author = {Davis, Sarah},
|
||||
title = {Thesis Title},
|
||||
school = {University Name},
|
||||
year = {2024}
|
||||
}
|
||||
```
|
||||
|
||||
**Website:**
|
||||
```bibtex
|
||||
@misc{citekey,
|
||||
author = {Organization},
|
||||
title = {Page Title},
|
||||
year = {2024},
|
||||
url = {https://example.com},
|
||||
note = {Accessed: 2024-11-16}
|
||||
}
|
||||
```
|
||||
|
||||
### BibTeX Field Reference
|
||||
|
||||
**Required vs Optional varies by entry type**
|
||||
|
||||
**Common Fields:**
|
||||
- `author` - Author names (use "and" to separate)
|
||||
- `title` - Work title
|
||||
- `year` - Publication year
|
||||
- `journal` - Journal name (article)
|
||||
- `booktitle` - Book/conference name
|
||||
- `publisher` - Publisher name
|
||||
- `school` - University (thesis)
|
||||
- `pages` - Page range (use double dash: 123--145)
|
||||
- `volume` - Volume number
|
||||
- `number` - Issue number
|
||||
- `edition` - Edition (2nd, 3rd, etc.)
|
||||
- `address` - Location (city, country)
|
||||
- `doi` - Digital Object Identifier
|
||||
- `url` - Web address
|
||||
- `note` - Additional information
|
||||
|
||||
**Author Formatting:**
|
||||
```bibtex
|
||||
author = {Lastname, Firstname}
|
||||
author = {Lastname1, Firstname1 and Lastname2, Firstname2}
|
||||
author = {Firstname Lastname} # Auto-parsed
|
||||
```
|
||||
|
||||
**Special Characters:**
|
||||
```bibtex
|
||||
title = {Study of {DNA} Sequencing} # Protect caps
|
||||
title = {Analysis of {IoT} Systems}
|
||||
author = {M{\"u}ller, Hans} # Umlaut
|
||||
```
|
||||
|
||||
## Example Complete Frontmatter
|
||||
|
||||
### Academic Paper
|
||||
```yaml
|
||||
---
|
||||
title: "Research Paper Title"
|
||||
author: "Author Name"
|
||||
date: "November 2024"
|
||||
lang: en-GB
|
||||
|
||||
bibliography: references.bib
|
||||
csl: harvard.csl
|
||||
link-citations: true
|
||||
|
||||
documentclass: report
|
||||
fontsize: 12pt
|
||||
geometry: margin=1in
|
||||
linestretch: 1.5
|
||||
numbersections: true
|
||||
|
||||
toc: true
|
||||
toc-depth: 3
|
||||
|
||||
header-includes: |
|
||||
\usepackage{graphicx}
|
||||
\usepackage{float}
|
||||
\usepackage{hyperref}
|
||||
---
|
||||
```
|
||||
|
||||
### Thesis
|
||||
```yaml
|
||||
---
|
||||
title: "Thesis Title"
|
||||
author: "Student Name"
|
||||
date: "Month Year"
|
||||
supervisor: "Dr. Supervisor Name"
|
||||
institution: "University Name"
|
||||
department: "Department Name"
|
||||
degree: "BSc Computer Science"
|
||||
lang: en-GB
|
||||
|
||||
bibliography: references.bib
|
||||
csl: harvard.csl
|
||||
link-citations: true
|
||||
|
||||
documentclass: report
|
||||
fontsize: 12pt
|
||||
geometry: margin=1in
|
||||
linestretch: 1.5
|
||||
numbersections: true
|
||||
secnumdepth: 3
|
||||
|
||||
toc: true
|
||||
toc-depth: 3
|
||||
lof: true
|
||||
lot: true
|
||||
---
|
||||
```
|
||||
|
||||
### Simple Article
|
||||
```yaml
|
||||
---
|
||||
title: "Article Title"
|
||||
author: "Author Name"
|
||||
date: "Date"
|
||||
lang: en-GB
|
||||
documentclass: article
|
||||
fontsize: 11pt
|
||||
geometry: margin=1in
|
||||
---
|
||||
```
|
||||
|
||||
## Variable Precedence
|
||||
|
||||
1. **Command-line variables** (`-V key=value`) override
|
||||
2. **Frontmatter variables**
|
||||
3. **Defaults file variables**
|
||||
4. **Pandoc built-in defaults**
|
||||
|
||||
## Resources
|
||||
|
||||
- **Pandoc Manual:** https://pandoc.org/MANUAL.html
|
||||
- **CSL Styles:** https://github.com/citation-style-language/styles
|
||||
- **BibTeX Reference:** https://www.bibtex.com/
|
||||
- **LaTeX Packages:** https://ctan.org/
|
||||
Reference in New Issue
Block a user