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

@@ -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 }}"

.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}'

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

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).

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 = """
+<!-- generated by git-cliff -->
+"""
+
+[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"