From e243a78c46f5ee0a4ffa334bf9ceb82d59b09f57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Moritz=20M=C3=A4hr?= Date: Thu, 2 Dec 2021 16:19:09 +0100 Subject: [PATCH] docs: Major rework of the docs and automatic Changelog added (#24) * docs: major rework of the docs * docs: automatic Changelog via cz and gitcliff-added * v0.0.8 added --- .github/workflows/changelog.yaml | 25 ++ .husky/pre-commit | 4 + .prettierignore | 1 - CHANGELOG.md | 7 + README.md | 190 ++++++++- cliff.toml | 54 +++ markdown.md | 595 --------------------------- package.json | 22 +- pdf.yaml | 2 +- template/academic-pandoc-template.md | 82 ++-- 10 files changed, 326 insertions(+), 656 deletions(-) create mode 100644 .github/workflows/changelog.yaml create mode 100755 .husky/pre-commit delete mode 100644 .prettierignore create mode 100644 cliff.toml delete mode 100644 markdown.md diff --git a/.github/workflows/changelog.yaml b/.github/workflows/changelog.yaml new file mode 100644 index 0000000..6f1fc9d --- /dev/null +++ b/.github/workflows/changelog.yaml @@ -0,0 +1,25 @@ +name: Create changelog + +on: [push] + +jobs: + changelog: + name: Generate changelog + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v2 + with: + fetch-depth: 0 + + - name: Generate a changelog + uses: orhun/git-cliff-action@v1 + id: git-cliff + with: + config: cliff.toml + args: --verbose + env: + OUTPUT: CHANGELOG.md + + - name: Print the changelog + run: cat "${{ steps.git-cliff.outputs.changelog }}" diff --git a/.husky/pre-commit b/.husky/pre-commit new file mode 100755 index 0000000..7240550 --- /dev/null +++ b/.husky/pre-commit @@ -0,0 +1,4 @@ +#!/bin/sh +. "$(dirname "$0")/_/husky.sh" + +pnpm exec prettier --ignore-path .gitignore --check . '!{CODE_OF_CONDUCT.md,LICENSE.md,_layouts/default.html,template/academic-pandoc-template.md}' diff --git a/.prettierignore b/.prettierignore deleted file mode 100644 index 8b13789..0000000 --- a/.prettierignore +++ /dev/null @@ -1 +0,0 @@ - diff --git a/CHANGELOG.md b/CHANGELOG.md index 63b85c6..b424310 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased](https://github.com/maehr/academic-pandoc-template/compare/...HEAD) +## [0.0.8](https://github.com/maehr/academic-pandoc-template/tree/v0.0.6) - 2021-12-02 + +### Documentation + +- Better docs +- Automatic changelog + ## [0.0.7](https://github.com/maehr/academic-pandoc-template/tree/v0.0.6) - 2021-07-11 ### Added diff --git a/README.md b/README.md index 11ccaaf..9d3f927 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Academic Pandoc template -Write beautiful academic texts with the distraction-free [Pandoc Markdown](http://pandoc.org/MANUAL.html) and [typademic](https://typademic.ch). +Write beautifully typeset academic texts with distraction-free [Markdown](https://daringfireball.net/projects/markdown/syntax) and [Pandoc](http://pandoc.org/MANUAL.html). [![GitHub issues](https://img.shields.io/github/issues/maehr/academic-pandoc-template.svg)](https://github.com/maehr/academic-pandoc-template/issues) [![GitHub forks](https://img.shields.io/github/forks/maehr/academic-pandoc-template.svg)](https://github.com/maehr/academic-pandoc-template/network) @@ -13,33 +13,182 @@ Write beautiful academic texts with the distraction-free [Pandoc Markdown](http: Read the [documentation](https://maehr.github.io/academic-pandoc-template/) and make sure you have a Markdown editor like [Zettlr](https://www.zettlr.com/) and a Bibtex editor like [JabRef](http://www.jabref.org/) installed. -### Use with [GitHub actions](https://docs.github.com/en/actions) +### Use it online 1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the [academic-pandoc-template](https://github.com/maehr/academic-pandoc-template) -2. Edit `/template/academic-pandoc-template.md` according to the [Markdown guide](https://maehr.github.io/academic-pandoc-template/markdown.html) [online](https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/editing-files-in-your-repository), with [Zettlr](https://www.zettlr.com/) or with your favorite Markdown editor +2. Edit `/template/academic-pandoc-template.md` according to the [Markdown guide](https://commonmark.org/help/tutorial/) [online](https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/editing-files-in-your-repository), with [Zettlr](https://www.zettlr.com/) or with your favorite Markdown editor 3. Edit `/template/references.bib` [online](https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/editing-files-in-your-repository), with [JabRef](http://www.jabref.org/) or with your favorite Bibtex editor 4. [Commit](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project) your changes 5. [GitHub actions](https://docs.github.com/en/actions/managing-workflow-runs/downloading-workflow-artifacts) will compile an updated PDF and a DOCX document and store these artifacts -### Use with [typademic](https://typademic.ch) online - -1. [Clone](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository-from-github/cloning-a-repository) or download the [academic-pandoc-template](https://github.com/maehr/academic-pandoc-template/archive/master.zip) -2. Edit `/template/academic-pandoc-template.md` according to the [Markdown guide](https://maehr.github.io/academic-pandoc-template/markdown.html) with [Zettlr](https://www.zettlr.com/) or your favorite Markdown editor -3. Edit `/template/references.bib` with [JabRef](http://www.jabref.org/) or your favorite Bibtex editor -4. Upload all files in `/template/` to [typademic](https://typademic.ch) and convert it to PDF or Docx - -### Use with Pandoc and Latex +### Use it locally Install all prerequisites - [Pandoc 2.11 or newer](http://pandoc.org/installing.html) -- [LaTeX](https://www.latex-project.org/get/) +- [Tectonic](https://tectonic-typesetting.github.io/) or another [LaTeX](https://www.latex-project.org/get/) distribution Open your command line and execute the following commands. ```bash -pandoc -d pdf.yaml -pandoc -d docx.yaml +pandoc --defaults pdf.yaml +pandoc --defaults docx.yaml +``` + +## Configuration + +### YAML metadata blocks + +Pandoc allows to write different [variables](https://pandoc.org/MANUAL.html#variables-for-latex) into the document via YAML metadata blocks in `template/academic-pandoc-template.md`. + +```markdown +--- +# Front matter +lang: de-CH +--- + +# Vowort + +(...) +``` + +#### Front matter + +```yaml +lang: de-CH # Use language codes like de, de-DE, en, en-UK, en-US, fr, it, ... +title: 'Ein schöner Titel' +subtitle: 'ein wundervoller Untertitel' +author: 'Petra Muster' +date: 30-06-2018 +abstract: 'Hier Vorgang ihm als reiße. Ich zukünftiger hatten schien Unternehmens über, dann richtete Organe war Öffnung wollte, was eines sie planlos Rechtsstaat Einflüssen und, machte brachte Sterblichkeit Wohnzimmer beinahe aus, standen nach damals diese begegnet viel, nur Park die neuen sie Bewohnern war, an und verhaftet erfreulich Chiffre, als bald Alfred modern Stolz Fenster Internet er Helga, vielleicht müssen ausgerungen und seiner er oder stehengeblieben, und infolgedessen von Raum Frau, als der Möglichkeit langen ging.' +keywords: 'Schlagworte, Worte' +thanks: 'Herzlichen Dank an Gabriela Muster für die wertvollen Kommentare.' +``` + +#### Bibliography + +```yaml +csl: https://www.zotero.org/styles/chicago-note-bibliography # See https://www.zotero.org/styles for more styles. +bibliography: references.bib # See https://github.com/jgm/pandoc-citeproc/blob/master/man/pandoc-citeproc.1.md for more formats. +suppress-bibliography: false +link-citations: true +color-links: true # See https://ctan.org/pkg/xcolor for colors +linkcolor: black +urlcolor: black +citecolor: black +endnote: false +``` + +#### Formatting + +```yaml +toc-title: 'Inhaltsverzeichnis' +toc: true # Table of contents +toc_depth: 2 +lof: true # List of figures +lot: true # List of tables +fontsize: 12pt +linestretch: 1.5 +mainfont: # See https://tug.org/FontCatalogue/seriffonts.html for fonts +sansfont: # See https://tug.org/FontCatalogue/sansseriffonts.html for fonts +monofont: # See https://tug.org/FontCatalogue/typewriterfonts.html for fonts +mathfont: # See https://tug.org/FontCatalogue/mathfonts.html for fonts +documentclass: report # See https://www.ctan.org/topic/class +classoption: [notitlepage, onecolumn, openany] +geometry: [a4paper, bindingoffset=0mm, inner=30mm, outer=30mm, top=30mm, bottom=30mm] # See https://ctan.org/pkg/geometry for more options +``` + +### Default files + +Pandoc accepts options via [default files](https://pandoc.org/MANUAL.html#default-files) for PDF-files in `pdf.yaml` and for Docx-files in `docx.yaml`. + +```yaml +cite-method: citeproc # citeproc, natbib, or biblatex +citeproc: true +file-scope: false # Parse each file individually before combining for multifile documents. This will allow footnotes in different files with the same identifiers to work as expected. If this option is set, footnotes and links will not work across files. +from: markdown +highlight-style: pygments # kate, monochrome, breezeDark, espresso, zenburn, haddock, tango +input-files: [template/academic-pandoc-template.md] +log-file: log/pdf.log.json +output-file: output/academic-pandoc-template.pdf +pdf-engine: tectonic # wkhtmltopdf, weasyprint, prince, pdflatex, lualatex, xelatex, latexmk, pdfroff, context +reference-location: block # block, section, or document +resource-path: [template] +standalone: true +to: pdf +top-level-division: chapter # part, chapter, section, or default: +verbosity: WARNING # ERROR, WARNING, or INFO +``` + +## LaTeX snippets + +````yaml +# LaTeX snippets +header-includes: + - | + ```{=latex} + \linepenalty=10 % the penalty added to the badness of each line within a paragraph (no associated penalty node) Increasing the value makes tex try to have fewer lines in the paragraph. + \interlinepenalty=0 % value of the penalty (node) added after each line of a paragraph. + \hyphenpenalty=50 % the penalty for line breaking at an automatically inserted hyphen + \exhyphenpenalty=50 % the penalty for line breaking at an explicit hyphen + \binoppenalty=700 % the penalty for breaking a line at a binary operator + \relpenalty=500 % the penalty for breaking a line at a relation + \clubpenalty=150 % extra penalty for breaking after first line of a paragraph + \widowpenalty=150 % extra penalty for breaking before last line of a paragraph + \displaywidowpenalty=50 % extra penalty for breaking before last line before a display math + \brokenpenalty=100 % extra penalty for page breaking after a hyphenated line + \predisplaypenalty=10000 % penalty for breaking before a display + \postdisplaypenalty=0 % penalty for breaking after a display + \floatingpenalty = 20000 % penalty for splitting an insertion (can only be split footnote in standard LaTeX) + ``` + - | + ```{=latex} + \raggedbottom % or \flushbottom + ``` + - | + ```{=latex} + % keep figures where there are in the text + \usepackage{float} + \floatplacement{figure}{H} + ``` + - | + ```{=latex} + % add custom hyphentation rules + \hyphenation + {% + Hyphenate-me-like-this + Dontyoueverhyphenateme + }% + ``` +```` + +## Linting and formatting + +Install the latest version of [Node](https://nodejs.org/) and all dependencies. + +```bash +npm install +``` + +To use linting and formatting, use the following commands. + +```bash +npm run check +npm run format +``` + +## Conventional Commits + +Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for adding human and machine readable meaning to commit messages. Install [commitizen](https://github.com/commitizen/cz-cli). + +```bash +npm install commitizen -g +``` + +To use Conventional Commits, use the following commands. + +```bash +npm run commit ``` ## Support @@ -54,9 +203,10 @@ This project is maintained by [@maehr](https://github.com/maehr). Please underst ## Built With -- [Chicago Manual of Style 17th edition (note)](https://www.zotero.org/styles?q=chicago) -- [LaTeX](https://www.latex-project.org/) -- [Pandoc](https://pandoc.org/) +- [Pandoc](https://pandoc.org/) a universal document converter and +- [Pandoc GitHub action](https://github.com/pandoc/pandoc-action-example) using the pandoc document converter on GitHub Actions +- [Prettier](https://prettier.io/), an opinionated code formatter +- [Tectonic](https://tectonic-typesetting.github.io/en-US/) is a modernized, complete, self-contained [TeX](https://www.tug.org/)/[LaTeX](https://www.latex-project.org/) engine, powered by [XeTeX](http://xetex.sourceforge.net/) and [TeXLive](https://www.tug.org/texlive/) ## Roadmap @@ -82,7 +232,5 @@ This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md ## Acknowledgments -- [John Gruber](https://daringfireball.net/projects/markdown/) -- [John MacFarlane](http://johnmacfarlane.net/) -- [Sarah Simpkin, "Getting Started with Markdown," The Programming Historian 4 (2015)](https://programminghistorian.org/en/lessons/getting-started-with-markdown) -- [Dennis Tenen and Grant Wythoff, "Sustainable Authorship in Plain Text using Pandoc and Markdown," The Programming Historian 3 (2014)](https://programminghistorian.org/en/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown) +- Sarah Simpkin, "Getting Started with Markdown," _Programming Historian_ 4 (2015), [https://doi.org/10.46430/phen0046](https://doi.org/10.46430/phen0046). +- Dennis Tenen and Grant Wythoff, "Sustainable Authorship in Plain Text using Pandoc and Markdown," _Programming Historian_ 3 (2014), [https://doi.org/10.46430/phen0041](https://doi.org/10.46430/phen0041). diff --git a/cliff.toml b/cliff.toml new file mode 100644 index 0000000..a215e4b --- /dev/null +++ b/cliff.toml @@ -0,0 +1,54 @@ +# configuration file for git-cliff (0.1.0) + +[changelog] +# changelog header +header = """ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n +""" +# template for the changelog body +# https://tera.netlify.app/docs/#introduction +body = """ +{% if version %}\ + ## [{{ version | replace(from="v", to="") }}] - {{ timestamp | date(format="%Y-%m-%d") }} +{% else %}\ + ## [unreleased] +{% endif %}\ +{% for group, commits in commits | group_by(attribute="group") %} + ### {{ group | upper_first }} + {% for commit in commits %} + - {{ commit.message | upper_first }}\ + {% endfor %} +{% endfor %}\n +""" +# remove the leading and trailing whitespaces from the template +trim = true +# changelog footer +footer = """ + +""" + +[git] +# allow only conventional commits +# https://www.conventionalcommits.org +conventional_commits = true +# regex for parsing and grouping commits +commit_parsers = [ + { message = "^*: add*", group = "Added"}, + { message = "^*: support*", group = "Added"}, + { message = "^*: remove*", group = "Removed"}, + { message = "^*: delete*", group = "Removed"}, + { message = "^test*", group = "Fixed"}, + { message = "^fix*", group = "Fixed"}, + { message = "^*: fix*", group = "Fixed"}, + { message = "^*", group = "Changed"}, +] +# filter out the commits that are not matched by commit parsers +filter_commits = true +# glob pattern for matching git tags +tag_pattern = "v[0-9]*" +# regex for skipping tags +skip_tags = "v0.1.0-beta.1" diff --git a/markdown.md b/markdown.md deleted file mode 100644 index 09b3770..0000000 --- a/markdown.md +++ /dev/null @@ -1,595 +0,0 @@ ---- -layout: default ---- - -# Write Markdown - -## Heading - -```markdown -# Heading 1 - -## Heading 2 - -### Heading 3 - -#### Heading 4 - -##### Heading 5 -``` - -## Emphasis - -```markdown -Emphasis, aka italics, with _asterisks_ or _underscores_. - -Strong emphasis, aka bold, with **asterisks** or **underscores**. - -Combined emphasis with **asterisks and _underscores_**. - -Strikethrough uses two tildes. ~~Scratch this.~~ -``` - -## Lists - -```markdown -1. First ordered list item -2. Another item - ⋅⋅\* Unordered sub-list. -3. Actual numbers don't matter, just that it's a number - ⋅⋅1. Ordered sub-list -4. And another item. - -⋅⋅⋅You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we'll use three here to also align the raw Markdown). - -⋅⋅⋅To have a line break without a paragraph, you will need to use two trailing spaces.⋅⋅ -⋅⋅⋅Note that this line is separate, but within the same paragraph.⋅⋅ -⋅⋅⋅(This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.) - -- Unordered list can use asterisks - -* Or minuses - -- Or pluses -``` - -## Links - -```markdown -[I'm an inline-style link](https://www.google.com) - -[I'm an inline-style link with title](https://www.google.com "Google's Homepage") - -[I'm a relative reference to a repository file](../blob/master/LICENSE.md) - -[You can use numbers for reference-style link definitions][1] - -Or leave it empty and use the [link text itself]. - -URLs and URLs in angle brackets will automatically get turned into links. -http://www.example.com or and sometimes -example.com (but not on Github, for example). -``` - -## Images - -```markdown -Save your image (jpg or png format only) to `template/` and insert it like this: - -![Figure caption text](template/cat.jpg 'Logo Title Text 1') -``` - -## Tables - -```markdown -Colons can be used to align columns. - -| Tables | Are | Cool | -| ------------- | :-----------: | ----: | -| col 3 is | right-aligned | $1600 | -| col 2 is | centered | $12 | -| zebra stripes | are neat | $1 | - -Table: Table captions are done like this. - -There must be at least 3 dashes separating each header cell. -The outer pipes (|) are optional, and you don't need to make the -raw Markdown line up prettily. You can also use inline Markdown. - -| Markdown | Less | Pretty | -| -------- | --------- | ---------- | -| _Still_ | `renders` | **nicely** | -| 1 | 2 | 3 | -``` - -## Blockquotes - -```markdown -> Blockquotes are very handy in email to emulate reply text. -> This line is part of the same quote. - -Quote break. - -> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can _put_ **Markdown** into a blockquote. -``` - -## Footnotes - -```markdown -Footnotes are best placed right after the paragraph first used.[^footnote] - -[^footnote]: But you can also put them at the end of the document. -``` - -If you want to use endnotes instead turn them on in document options. - -## Comments - -```markdown - -``` - -# Citations and bibliographies - -## Citations JabRef - -1. Open `template/references.bib` with [JabRef](https://www.jabref.org/). - -2. Insert, delete or modify references (set the CiteKey and memorize it for later use) - -3. Save the file - -![JabRef](jab-ref.png) - -## Add citations to your document - -```markdown -Citations go inside square brackets and are separated by semicolons. Each citation must have a key, composed of ‘@’ + the citation identifier from the database, and may optionally have a prefix, a locator, and a suffix. Here are some examples: - -Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1]. - -Blah blah [@doe99, pp. 33-35, 38-39 and *passim*]. - -Blah blah [@smith04; @doe99]. - -A minus sign (-) before the @ will suppress mention of the author in the citation. This can be useful when the author is already mentioned in the text: - -Smith says blah [-@smith04]. - -You can also write an in-text citation, as follows: - -@smith04 says blah. - -@smith04 [p. 33] says blah. -``` - -## Change citations style - -Choose a style from the list [CSL-Repository](https://www.zotero.org/styles) (or its corresponding [GitHub Repo](https://github.com/citation-style-language/styles)) and overwrite `template/style.csl`. - -## Bibliography - -The last heading without any text following will be the heading for the bibliography. - -# Advanced Formatting [(Taken from Pandoc Manual)](http://pandoc.org/MANUAL.html#variables-for-latex) - -The Academic Pandoc Template already comes with a predefined header block in `template/academic-pandoc-template.md` which looks like this: - -```yaml ---- -# Front matter -lang: de-CH # Use language codes like de, de-DE, en, en-UK, en-US, fr, it, ... -title: 'Ein schöner Titel' -subtitle: 'ein wundervoller Untertitel' -author: 'Petra Muster' -date: 30-06-2018 -abstract: 'Hier Vorgang ihm als reiße. Ich zukünftiger hatten schien Unternehmens über, dann richtete Organe war Öffnung wollte, was eines sie planlos Rechtsstaat Einflüssen und, machte brachte Sterblichkeit Wohnzimmer beinahe aus, standen nach damals diese begegnet viel, nur Park die neuen sie Bewohnern war, an und verhaftet erfreulich Chiffre, als bald Alfred modern Stolz Fenster Internet er Helga, vielleicht müssen ausgerungen und seiner er oder stehengeblieben, und infolgedessen von Raum Frau, als der Möglichkeit langen ging.' -keywords: 'Schlagworte, Worte' -thanks: 'Herzlichen Dank an Gabriela Muster für die wertvollen Kommentare.' - -# Bibliography -csl: https://www.zotero.org/styles/chicago-note-bibliography # See https://www.zotero.org/styles for more styles. -bibliography: references.bib # See https://github.com/jgm/pandoc-citeproc/blob/master/man/pandoc-citeproc.1.md for more formats. -suppress-bibliography: false -link-citations: true -color-links: true # See https://ctan.org/pkg/xcolor for colors -linkcolor: black -urlcolor: black -citecolor: black -endnote: false - -# Formatting -toc-title: 'Inhaltsverzeichnis' -toc: true # Table of contents -toc_depth: 2 -lof: true # List of figures -lot: true # List of tables -fontsize: 12pt -linestretch: 1.5 -# Uncomment and check https://tug.org/FontCatalogue/ and https://fonts.google.com/ for fonts -# mainfont: "Merriweather" -# sansfont: "Raleway" -# monofont: "IBM Plex Mono" -# mathfont: -documentclass: report # See https://en.wikibooks.org/wiki/LaTeX/Document_Structure#Document_classes for more classes and options -classoption: [notitlepage, onecolumn, openany] -geometry: [a4paper, bindingoffset=0mm, inner=30mm, outer=30mm, top=30mm, bottom=30mm] # See https://ctan.org/pkg/geometry for more options -header-includes: - - \linepenalty=10 # the penalty added to the badness of each line within a paragraph (no associated penalty node) Increasing the value makes tex try to have fewer lines in the paragraph. - - \interlinepenalty=0 # value of the penalty (node) added after each line of a paragraph. - - \hyphenpenalty=50 # the penalty for line breaking at an automatically inserted hyphen - - \exhyphenpenalty=50 # the penalty for line breaking at an explicit hyphen - - \binoppenalty=700 # the penalty for breaking a line at a binary operator - - \relpenalty=500 # the penalty for breaking a line at a relation - - \clubpenalty=150 # extra penalty for breaking after first line of a paragraph - - \widowpenalty=150 # extra penalty for breaking before last line of a paragraph - - \displaywidowpenalty=50 # extra penalty for breaking before last line before a display math - - \brokenpenalty=100 # extra penalty for page breaking after a hyphenated line - - \predisplaypenalty=10000 # penalty for breaking before a display - - \postdisplaypenalty=0 # penalty for breaking after a display - - \floatingpenalty = 20000 # penalty for splitting an insertion (can only be split footnote in standard LaTeX) - - \raggedbottom # or \flushbottom - - \usepackage{float} # keep figures where there are in the text - - \floatplacement{figure}{H} # keep figures where there are in the text -# if you use RStudio uncomment these lines -# output: -# word_document: -# path: academic-pandoc-template.docx -# pdf_document: -# path: academic-pandoc-template.pdf ---- - -``` - -You can easily add, remove or modify these variables by editing the corresponding value. - -## Variables - -### Metadata variables - -`title`, `author`, `date` - -allow identification of basic aspects of the document. Included in PDF metadata through LaTeX and ConTeXt. These can be set through a [pandoc title block](https://pandoc.org/MANUAL.html#extension-pandoc_title_block), which allows for multiple authors, or through a [YAML metadata block](https://pandoc.org/MANUAL.html#extension-yaml_metadata_block): - -``` ---- -author: -- Aristotle -- Peter Abelard -... -``` - -Note that if you just want to set PDF or HTML metadata, without including a title block in the document itself, you can set the `title-meta`, `author-meta`, and `date-meta` variables. (By default these are set automatically, based on `title`, `author`, and `date`.) The page title in HTML is set by `pagetitle`, which is equal to `title` by default. - -`subtitle` - -document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx documents - -`abstract` - -document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx documents - -`keywords` - -list of keywords to be included in HTML, PDF, ODT, pptx, docx and AsciiDoc metadata; repeat as for `author`, above - -`subject` - -document subject, included in ODT, PDF, docx and pptx metadata - -`description` - -document description, included in ODT, docx and pptx metadata. Some applications show this as `Comments` metadata. - -`category` - -document category, included in docx and pptx metadata - -Additionally, any root-level string metadata, not included in ODT, docx or pptx metadata is added as a _custom property_. The following [YAML](https://yaml.org/spec/1.2/spec.html 'YAML v1.2 Spec') metadata block for instance: - -``` ---- -title: 'This is the title' -subtitle: "This is the subtitle" -author: -- Author One -- Author Two -description: | - This is a long - description. - - It consists of two paragraphs -... -``` - -will include `title`, `author` and `description` as standard document properties and `subtitle` as a custom property when converting to docx, ODT or pptx. - -### Language variables - -`lang` - -identifies the main language of the document using IETF language tags (following the [BCP 47](https://tools.ietf.org/html/bcp47) standard), such as `en` or `en-GB`. The [Language subtag lookup](https://r12a.github.io/app-subtags/) tool can look up or verify these tags. This affects most formats, and controls hyphenation in PDF output when using LaTeX (through [`babel`](https://ctan.org/pkg/babel) and [`polyglossia`](https://ctan.org/pkg/polyglossia)) or ConTeXt. - -Use native pandoc [Divs and Spans](https://pandoc.org/MANUAL.html#divs-and-spans) with the `lang` attribute to switch the language: - -``` ---- -lang: en-GB -... - -Text in the main document language (British English). - -::: {lang=fr-CA} -> Cette citation est écrite en français canadien. -::: - -More text in English. ['Zitat auf Deutsch.']{lang=de} -``` - -`dir` - -the base script direction, either `rtl` (right-to-left) or `ltr` (left-to-right). - -For bidirectional documents, native pandoc `span`s and `div`s with the `dir` attribute (value `rtl` or `ltr`) can be used to override the base direction in some output formats. This may not always be necessary if the final renderer (e.g. the browser, when generating HTML) supports the [Unicode Bidirectional Algorithm](https://www.w3.org/International/articles/inline-bidi-markup/uba-basics). - -When using LaTeX for bidirectional documents, only the `xelatex` engine is fully supported (use [`--pdf-engine=xelatex`](https://pandoc.org/MANUAL.html#option--pdf-engine)). - -### Variables for LaTeX - -Pandoc uses these variables when [creating a PDF](https://pandoc.org/MANUAL.html#creating-a-pdf) with a LaTeX engine. - -#### Layout - -`block-headings` - -make `\paragraph` and `\subparagraph` (fourth- and fifth-level headings, or fifth- and sixth-level with book classes) free-standing rather than run-in; requires further formatting to distinguish from `\subsubsection` (third- or fourth-level headings). Instead of using this option, [KOMA-Script](https://ctan.org/pkg/koma-script) can adjust headings more extensively: - -``` ---- -documentclass: scrartcl -header-includes: | - \RedeclareSectionCommand[ - beforeskip=-10pt plus -2pt minus -1pt, - afterskip=1sp plus -1sp minus 1sp, - font=\normalfont\itshape]{paragraph} - \RedeclareSectionCommand[ - beforeskip=-10pt plus -2pt minus -1pt, - afterskip=1sp plus -1sp minus 1sp, - font=\normalfont\scshape, - indent=0pt]{subparagraph} -... -``` - -`classoption` - -option for document class, e.g. `oneside`; repeat for multiple options: - -``` ---- -classoption: -- twocolumn -- landscape -... -``` - -`documentclass` - -document class: usually one of the standard classes, [`article`](https://ctan.org/pkg/article), [`book`](https://ctan.org/pkg/book), and [`report`](https://ctan.org/pkg/report); the [KOMA-Script](https://ctan.org/pkg/koma-script) equivalents, `scrartcl`, `scrbook`, and `scrreprt`, which default to smaller margins; or [`memoir`](https://ctan.org/pkg/memoir) - -`geometry` - -option for [`geometry`](https://ctan.org/pkg/geometry) package, e.g. `margin=1in`; repeat for multiple options: - -``` ---- -geometry: -- top=30mm -- left=20mm -- heightrounded -... -``` - -`hyperrefoptions` - -option for [`hyperref`](https://ctan.org/pkg/hyperref) package, e.g. `linktoc=all`; repeat for multiple options: - -``` ---- -hyperrefoptions: -- linktoc=all -- pdfwindowui -- pdfpagemode=FullScreen -... -``` - -`indent` - -if true, pandoc will use document class settings for indentation (the default LaTeX template otherwise removes indentation and adds space between paragraphs) - -`linestretch` - -adjusts line spacing using the [`setspace`](https://ctan.org/pkg/setspace) package, e.g. `1.25`, `1.5` - -`margin-left`, `margin-right`, `margin-top`, `margin-bottom` - -sets margins if `geometry` is not used (otherwise `geometry` overrides these) - -`pagestyle` - -control `\pagestyle{}`: the default article class supports `plain` (default), `empty` (no running heads or page numbers), and `headings` (section titles in running heads) - -`papersize` - -paper size, e.g. `letter`, `a4` - -`secnumdepth` - -numbering depth for sections (with [`--number-sections`](https://pandoc.org/MANUAL.html#option--number-sections) option or `numbersections` variable) - -#### Fonts - -`fontenc` - -allows font encoding to be specified through `fontenc` package (with `pdflatex`); default is `T1` (see [LaTeX font encodings guide](https://ctan.org/pkg/encguide)) - -`fontfamily` - -font package for use with `pdflatex`: [TeX Live](https://www.tug.org/texlive/) includes many options, documented in the [LaTeX Font Catalogue](https://tug.org/FontCatalogue/). The default is [Latin Modern](https://ctan.org/pkg/lm). - -`fontfamilyoptions` - -options for package used as `fontfamily`; repeat for multiple options. For example, to use the Libertine font with proportional lowercase (old-style) figures through the [`libertinus`](https://ctan.org/pkg/libertinus) package: - -``` ---- -fontfamily: libertinus -fontfamilyoptions: -- osf -- p -... -``` - -`fontsize` - -font size for body text. The standard classes allow 10pt, 11pt, and 12pt. To use another size, set `documentclass` to one of the [KOMA-Script](https://ctan.org/pkg/koma-script) classes, such as `scrartcl` or `scrbook`. - -`mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont` - -font families for use with `xelatex` or `lualatex`: take the name of any system font, using the [`fontspec`](https://ctan.org/pkg/fontspec) package. `CJKmainfont` uses the [`xecjk`](https://ctan.org/pkg/xecjk) package. - -`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions` - -options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont` in `xelatex` and `lualatex`. Allow for any choices available through [`fontspec`](https://ctan.org/pkg/fontspec); repeat for multiple options. For example, to use the [TeX Gyre](http://www.gust.org.pl/projects/e-foundry/tex-gyre) version of Palatino with lowercase figures: - -``` ---- -mainfont: TeX Gyre Pagella -mainfontoptions: -- Numbers=Lowercase -- Numbers=Proportional -... -``` - -`microtypeoptions` - -options to pass to the microtype package - -#### Links - -`colorlinks` - -add color to link text; automatically enabled if any of `linkcolor`, `filecolor`, `citecolor`, `urlcolor`, or `toccolor` are set - -`linkcolor`, `filecolor`, `citecolor`, `urlcolor`, `toccolor` - -color for internal links, external links, citation links, linked URLs, and links in table of contents, respectively: uses options allowed by [`xcolor`](https://ctan.org/pkg/xcolor), including the `dvipsnames`, `svgnames`, and `x11names` lists - -`links-as-notes` - -causes links to be printed as footnotes - -#### Front matter - -`lof`, `lot` - -include list of figures, list of tables - -`thanks` - -contents of acknowledgments footnote after document title - -`toc` - -include table of contents (can also be set using [`--toc/--table-of-contents`](https://pandoc.org/MANUAL.html#option--toc)) - -`toc-depth` - -level of section to include in table of contents - -#### BibLaTeX Bibliographies - -These variables function when using BibLaTeX for [citation rendering](https://pandoc.org/MANUAL.html#citation-rendering). - -`biblatexoptions` - -list of options for biblatex - -`biblio-style` - -bibliography style, when used with [`--natbib`](https://pandoc.org/MANUAL.html#option--natbib) and [`--biblatex`](https://pandoc.org/MANUAL.html#option--biblatex). - -`biblio-title` - -bibliography title, when used with [`--natbib`](https://pandoc.org/MANUAL.html#option--natbib) and [`--biblatex`](https://pandoc.org/MANUAL.html#option--biblatex). - -`bibliography` - -bibliography to use for resolving references - -`natbiboptions` - -list of options for natbib - -### Variables set automatically - -Pandoc sets these variables automatically in response to [options](https://pandoc.org/MANUAL.html#options) or document contents; users can also modify them. These vary depending on the output format, and include the following: - -`body` - -body of document - -`date-meta` - -the `date` variable converted to ISO 8601 YYYY-MM-DD, included in all HTML based formats (dzslides, epub, html, html4, html5, revealjs, s5, slideous, slidy). The recognized formats for `date` are: `mm/dd/yyyy`, `mm/dd/yy`, `yyyy-mm-dd` (ISO 8601), `dd MM yyyy` (e.g. either `02 Apr 2018` or `02 April 2018`), `MM dd, yyyy` (e.g. `Apr. 02, 2018` or `April 02, 2018),`yyyy[mm[dd]]]`(e.g.`20180402, `201804` or `2018`). - -`header-includes` - -contents specified by [`-H/--include-in-header`](https://pandoc.org/MANUAL.html#option--include-in-header) (may have multiple values) - -`include-before` - -contents specified by [`-B/--include-before-body`](https://pandoc.org/MANUAL.html#option--include-before-body) (may have multiple values) - -`include-after` - -contents specified by [`-A/--include-after-body`](https://pandoc.org/MANUAL.html#option--include-after-body) (may have multiple values) - -`meta-json` - -JSON representation of all of the document’s metadata. Field values are transformed to the selected output format. - -`numbersections` - -non-null value if [`-N/--number-sections`](https://pandoc.org/MANUAL.html#option--number-sections) was specified - -`sourcefile`, `outputfile` - -source and destination filenames, as given on the command line. `sourcefile` can also be a list if input comes from multiple files, or empty if input is from stdin. You can use the following snippet in your template to distinguish them: - -``` -$if(sourcefile)$ -$for(sourcefile)$ -$sourcefile$ -$endfor$ -$else$ -(stdin) -$endif$ -``` - -Similarly, `outputfile` can be `-` if output goes to the terminal. - -If you need absolute paths, use e.g. `$curdir$/$sourcefile$`. - -`curdir` - -working directory from which pandoc is run. - -`toc` - -non-null value if [`--toc/--table-of-contents`](https://pandoc.org/MANUAL.html#option--toc) was specified - -`toc-title` - -title of table of contents (works only with EPUB, HTML, opendocument, odt, docx, pptx, beamer, LaTeX) - -[back](./) diff --git a/package.json b/package.json index cda9987..9613772 100644 --- a/package.json +++ b/package.json @@ -1,12 +1,26 @@ { "name": "academic-pandoc-template", - "version": "0.0.7", + "version": "0.0.8", "scripts": { - "lint": "prettier --check --plugin-search-dir=. . && eslint --ignore-path .gitignore .", - "format": "prettier --write --plugin-search-dir=. ." + "check": "prettier --ignore-path .gitignore --check . '!{CODE_OF_CONDUCT.md,LICENSE.md,_layouts/default.html}'", + "commit": "cz", + "format": "prettier --ignore-path .gitignore --write . '!{CODE_OF_CONDUCT.md,LICENSE.md,_layouts/default.html}'", + "prepare": "husky install" }, "devDependencies": { + "cz-conventional-changelog": "^3.3.0", + "husky": "^7.0.4", "prettier": "~2.2.1" }, - "type": "module" + "type": "module", + "config": { + "commitizen": { + "path": "./node_modules/cz-conventional-changelog" + }, + "husky": { + "hooks": { + "prepare-commit-msg": "exec < /dev/tty && git cz --hook || true" + } + } + } } diff --git a/pdf.yaml b/pdf.yaml index 5d73246..ce1cb80 100644 --- a/pdf.yaml +++ b/pdf.yaml @@ -6,7 +6,7 @@ highlight-style: pygments input-files: [template/academic-pandoc-template.md] log-file: log/pdf.log.json output-file: output/academic-pandoc-template.pdf -pdf-engine: tectonic +pdf-engine: tectonic # wkhtmltopdf, weasyprint, prince, pdflatex, lualatex, xelatex, latexmk, pdfroff, context reference-location: block # block, section, or document resource-path: [template] standalone: true diff --git a/template/academic-pandoc-template.md b/template/academic-pandoc-template.md index a646dc7..3e40b17 100644 --- a/template/academic-pandoc-template.md +++ b/template/academic-pandoc-template.md @@ -28,37 +28,51 @@ lof: true # List of figures lot: true # List of tables fontsize: 12pt linestretch: 1.5 -# Uncomment and check https://tug.org/FontCatalogue/ and https://fonts.google.com/ for fonts -# mainfont: "Merriweather" -# sansfont: "Raleway" -# monofont: "IBM Plex Mono" -# mathfont: -documentclass: report # See https://en.wikibooks.org/wiki/LaTeX/Document_Structure#Document_classes for more classes and options +mainfont: # See https://tug.org/FontCatalogue/seriffonts.html for fonts +sansfont: # See https://tug.org/FontCatalogue/sansseriffonts.html for fonts +monofont: # See https://tug.org/FontCatalogue/typewriterfonts.html for fonts +mathfont: # See https://tug.org/FontCatalogue/mathfonts.html for fonts +documentclass: report # See https://www.ctan.org/topic/class classoption: [notitlepage, onecolumn, openany] geometry: [a4paper, bindingoffset=0mm, inner=30mm, outer=30mm, top=30mm, bottom=30mm] # See https://ctan.org/pkg/geometry for more options + +# LaTeX snippets header-includes: - - \linepenalty=10 # the penalty added to the badness of each line within a paragraph (no associated penalty node) Increasing the value makes tex try to have fewer lines in the paragraph. - - \interlinepenalty=0 # value of the penalty (node) added after each line of a paragraph. - - \hyphenpenalty=50 # the penalty for line breaking at an automatically inserted hyphen - - \exhyphenpenalty=50 # the penalty for line breaking at an explicit hyphen - - \binoppenalty=700 # the penalty for breaking a line at a binary operator - - \relpenalty=500 # the penalty for breaking a line at a relation - - \clubpenalty=150 # extra penalty for breaking after first line of a paragraph - - \widowpenalty=150 # extra penalty for breaking before last line of a paragraph - - \displaywidowpenalty=50 # extra penalty for breaking before last line before a display math - - \brokenpenalty=100 # extra penalty for page breaking after a hyphenated line - - \predisplaypenalty=10000 # penalty for breaking before a display - - \postdisplaypenalty=0 # penalty for breaking after a display - - \floatingpenalty = 20000 # penalty for splitting an insertion (can only be split footnote in standard LaTeX) - - \raggedbottom # or \flushbottom - - \usepackage{float} # keep figures where there are in the text - - \floatplacement{figure}{H} # keep figures where there are in the text -# if you use RStudio uncomment these lines -# output: -# word_document: -# path: academic-pandoc-template.docx -# pdf_document: -# path: academic-pandoc-template.pdf + - | + ```{=latex} + \linepenalty=10 % the penalty added to the badness of each line within a paragraph (no associated penalty node) Increasing the value makes tex try to have fewer lines in the paragraph. + \interlinepenalty=0 % value of the penalty (node) added after each line of a paragraph. + \hyphenpenalty=50 % the penalty for line breaking at an automatically inserted hyphen + \exhyphenpenalty=50 % the penalty for line breaking at an explicit hyphen + \binoppenalty=700 % the penalty for breaking a line at a binary operator + \relpenalty=500 % the penalty for breaking a line at a relation + \clubpenalty=150 % extra penalty for breaking after first line of a paragraph + \widowpenalty=150 % extra penalty for breaking before last line of a paragraph + \displaywidowpenalty=50 % extra penalty for breaking before last line before a display math + \brokenpenalty=100 % extra penalty for page breaking after a hyphenated line + \predisplaypenalty=10000 % penalty for breaking before a display + \postdisplaypenalty=0 % penalty for breaking after a display + \floatingpenalty = 20000 % penalty for splitting an insertion (can only be split footnote in standard LaTeX) + ``` + - | + ```{=latex} + \raggedbottom % or \flushbottom + ``` + - | + ```{=latex} + % keep figures where there are in the text + \usepackage{float} + \floatplacement{figure}{H} + ``` + - | + ```{=latex} + % add custom hyphentation rules + \hyphenation + {% + Hyphenate-me-like-this + Dontyoueverhyphenateme + }% + ``` --- # Vowort @@ -129,9 +143,9 @@ Die unmöglich selbst mehreren hätte ist, denn sechziger zurücksehnte langweil ## Betonung -Hervorhebung, auch kursiv, mit _Sternchen_ oder _Unterstrichen_. +Hervorhebung, auch kursiv, mit *Sternchen* oder _Unterstrichen_. -Starke Betonung, auch bekannt als fett, mit **asterisks** oder **underscores**. +Starke Betonung, auch bekannt als fett,it **Sternchen** oder __Unterstrichen__. Kombinierte Betonung mit **asterisks und _Unterstrichen_**. @@ -154,11 +168,11 @@ Durchgestrichen wird mit zwei Tilden. ~~Streichrn Sie das hier.~~ Merke, dass diese Zeile getrennt ist, aber innerhalb desselben Absatzes. (Dies steht im Widerspruch zum typischen GFM-Zeilenumbruchverhalten, bei dem keine Leerzeichen erforderlich sind. -- Ungeordnete Liste kann Sternchen enthalten +* Ungeordnete Liste kann Sternchen enthalten -* Oder Minus +- Oder Minus -- Oder Pluspunkte ++ Oder Pluspunkte ## Links @@ -251,7 +265,7 @@ Das funktioniert jedoch nur mit Zitierstilen wie APA oder Chicago. ## Zitierweise ändern -Wählen Sie einen Stil aus der Liste [CSL-Repository](https://www.zotero.org/styles) oder den entsprechenden [GitHub Repo](https://github.com/citation-style-language/styles) und ändern Sie die Zeile `bibliography`. +Wählen Sie einen Stil aus der Liste [CSL-Repository](https://www.zotero.org/styles) oder dem entsprechenden [GitHub Repo](https://github.com/citation-style-language/styles) und ändern Sie die Zeile `bibliography`. # Literaturverzeichnis