mirror of
https://github.com/Wandmalfarbe/pandoc-latex-template.git
synced 2025-02-04 10:10:54 +00:00
Update README.md
## [2024-05-20] ### Added - Custom colors for headings, captions, blockquotes, and listings. - Custom commands `\customheading` and `\customcaption` for flexible styling. - Support for custom background images on title pages and all pages. - Flexible geometry settings for title page layout. - Enhanced handling of paragraph and list spacing. ### Changed - Updated README.md to include detailed instructions on using and customizing the template. - Integrated custom styling options directly into the template for better user experience.
This commit is contained in:
Kai
GitHub
parent
774c5e7897
commit
aa8b05d27b
179
README.md
179
README.md
@ -1,4 +1,4 @@
|
||||
<img src="icon.png" align="right" height="110"/>
|
||||
markdownCopy code<img src="icon.png" align="right" height="110"/>
|
||||
|
||||
# Eisvogel
|
||||
|
||||
@ -39,34 +39,38 @@ docker run --rm \
|
||||
|
||||
For frequent command line use, you can define the following shell alias:
|
||||
|
||||
``` bash
|
||||
```
|
||||
bash
|
||||
Copy code
|
||||
alias pandock='docker run --rm -v "$(pwd):/data" -u $(id -u):$(id -g) pandoc/extra'
|
||||
```
|
||||
|
||||
The example invocation with Docker from above now looks like this:
|
||||
|
||||
``` bash
|
||||
```
|
||||
bash
|
||||
Copy code
|
||||
pandock example.md -o example.pdf --template eisvogel --listings
|
||||
```
|
||||
|
||||
[pandoc/extra]: https://hub.docker.com/r/pandoc/extra
|
||||
|
||||
## Usage
|
||||
|
||||
1. Open the terminal and navigate to the folder where your markdown file is located.
|
||||
|
||||
2. Execute the following command
|
||||
|
||||
``` bash
|
||||
```
|
||||
bash
|
||||
Copy code
|
||||
pandoc example.md -o example.pdf --from markdown --template eisvogel --listings
|
||||
```
|
||||
|
||||
where `example.md` is the markdown file you want to convert to PDF.
|
||||
|
||||
In order to have nice headers and footers you need to supply metadata to your document. You can do that with a [YAML metadata block](http://pandoc.org/MANUAL.html#extension-yaml_metadata_block) at the top of your markdown document (see the [example markdown file](examples/basic-example/document.md)). Your markdown document may look like the following:
|
||||
In order to have nice headers and footers you need to supply metadata to your document. You can do that with a [YAML metadata block](http://pandoc.org/MANUAL.html#extension-yaml_metadata_block) at the top of your markdown document (see the [example markdown file](https://chatgpt.com/c/examples/basic-example/document.md)). Your markdown document may look like the following:
|
||||
|
||||
``` markdown
|
||||
---
|
||||
```
|
||||
markdownCopy code---
|
||||
title: "The Document Title"
|
||||
author: [Example Author, Another Author]
|
||||
date: "2017-02-20"
|
||||
@ -86,7 +90,7 @@ This template defines some new variables to control the appearance of the result
|
||||
|
||||
- `titlepage-color`
|
||||
|
||||
the background color of the title page. The color value must be given as an HTML hex color like `D8DE2C` without the leading number sign (`#`). When specifying the color in YAML, it is advisable to enclose it in quotes like so `titlepage-color: "D8DE2C"` to avoid the truncation of the color (e.g. `000000` becoming `0`).
|
||||
the background color of the title page. The color value must be given as an HTML hex color like `D8DE2C` without the leading number sign (`#`). When specifying the color in YAML, it is advisable to enclose it in quotes like so `titlepage-color: "D8DE2C"` to avoid the truncation of the color (e.g. `000000` becoming `0`).
|
||||
|
||||
- `titlepage-text-color` (defaults to `5F5F5F`)
|
||||
|
||||
@ -189,7 +193,7 @@ This template defines some new variables to control the appearance of the result
|
||||
- `em`: Nominal m-width
|
||||
- `px`: Pixel (only for pdfTeX and LuaTeX) The dimension given to the `\pdfpxdimen` primitive; default value is 1 `bp`, corresponding to a pixel density of 72 dpi.
|
||||
|
||||
A visual overview of the length units is available at <https://github.com/tweh/tex-units>.
|
||||
A visual overview of the length units is available at https://github.com/tweh/tex-units.
|
||||
|
||||
- `first-chapter` (defaults to `1`)
|
||||
|
||||
@ -197,7 +201,7 @@ This template defines some new variables to control the appearance of the result
|
||||
|
||||
- `float-placement-figure` (defaults to `H`)
|
||||
|
||||
Reset the default placement specifier for figure environments to the supplied value e.g. `htbp`. The available specifiers are listed below. The first four placement specifiers can be combined.
|
||||
Reset the default placement specifier for figure environments to the supplied value e.g. `htbp`. The available specifiers are listed below. The first four placement specifiers can be combined.
|
||||
|
||||
1. `h`: Place the float *here*, i.e., approximately at the same point it occurs in the source text.
|
||||
2. `t`: Place the float at the *top* of the page.
|
||||
@ -215,13 +219,10 @@ This template defines some new variables to control the appearance of the result
|
||||
|
||||
## Required LaTeX Packages
|
||||
|
||||
LaTeX manages addons and additional functionality in so called packages. You
|
||||
might get the following error when compiling a document with the Eisvogel
|
||||
template:
|
||||
LaTeX manages addons and additional functionality in so called packages. You might get the following error when compiling a document with the Eisvogel template:
|
||||
|
||||
|
||||
``` sh
|
||||
! LaTeX Error: File `footnotebackref.sty' not found.
|
||||
```
|
||||
shCopy code! LaTeX Error: File `footnotebackref.sty' not found.
|
||||
|
||||
Type X to quit or <RETURN> to proceed,
|
||||
or enter new name. (Default extension: sty)
|
||||
@ -231,21 +232,16 @@ Enter file name:
|
||||
<read *>
|
||||
```
|
||||
|
||||
LaTeX informs you that the additional package `footnotebackref` is required to
|
||||
render the document.
|
||||
LaTeX informs you that the additional package `footnotebackref` is required to render the document.
|
||||
|
||||
### Texlive
|
||||
|
||||
Eisvogel requires a full texlive distribution that can be installed by running
|
||||
`apt-get install texlive-full` in the terminal. Because `texlive-full` is very
|
||||
large (about 5 Gigabytes) you can also install the smaller texlive bundles and
|
||||
add any missing packages manually.
|
||||
Eisvogel requires a full texlive distribution that can be installed by running `apt-get install texlive-full` in the terminal. Because `texlive-full` is very large (about 5 Gigabytes) you can also install the smaller texlive bundles and add any missing packages manually.
|
||||
|
||||
A smaller texlive bundle is `texlive-latex-extra`. With `texlive-latex-extra`
|
||||
you also need to install these packages manually:
|
||||
A smaller texlive bundle is `texlive-latex-extra`. With `texlive-latex-extra` you also need to install these packages manually:
|
||||
|
||||
```
|
||||
adjustbox babel-german background bidi collectbox csquotes everypage filehook
|
||||
arduinoCopy codeadjustbox babel-german background bidi collectbox csquotes everypage filehook
|
||||
footmisc footnotebackref framed fvextra letltxmacro ly1 mdframed mweights
|
||||
needspace pagecolor sourcecodepro sourcesanspro titling ucharcat ulem
|
||||
unicode-math upquote xecjk xurl zref
|
||||
@ -253,20 +249,19 @@ unicode-math upquote xecjk xurl zref
|
||||
|
||||
Install them with the following command:
|
||||
|
||||
``` sh
|
||||
```
|
||||
sh
|
||||
Copy code
|
||||
tlmgr install adjustbox babel-german background bidi collectbox csquotes everypage filehook footmisc footnotebackref framed fvextra letltxmacro ly1 mdframed mweights needspace pagecolor sourcecodepro sourcesanspro titling ucharcat ulem unicode-math upquote xecjk xurl zref
|
||||
```
|
||||
|
||||
Additional information about the different texlive packages can be found at
|
||||
this TeX-StackExchange answer: <https://tex.stackexchange.com/a/504566>
|
||||
Additional information about the different texlive packages can be found at this TeX-StackExchange answer: https://tex.stackexchange.com/a/504566
|
||||
|
||||
### MiKTeX
|
||||
|
||||
If you don't want to install all missing packages manually, [MiKTeX might be
|
||||
an alternative](https://miktex.org/howto/miktex-console).
|
||||
If you don't want to install all missing packages manually, [MiKTeX might be an alternative](https://miktex.org/howto/miktex-console).
|
||||
|
||||
> MiKTeX has the ability to automatically install missing packages.
|
||||
> You can turn this feature on or off. And you can let MiKTeX ask you each time a package has to be installed:
|
||||
> MiKTeX has the ability to automatically install missing packages. You can turn this feature on or off. And you can let MiKTeX ask you each time a package has to be installed:
|
||||
>
|
||||
> - Click `Settings` to navigate to the settings page.
|
||||
> - Click the `General` tab.
|
||||
@ -281,7 +276,9 @@ an alternative](https://miktex.org/howto/miktex-console).
|
||||
|
||||
For PDFs with [numbered sections](http://pandoc.org/MANUAL.html#options-affecting-specific-writers) use the `--number-sections` or `-N` option.
|
||||
|
||||
``` bash
|
||||
```
|
||||
bash
|
||||
Copy code
|
||||
pandoc example.md -o example.pdf --template eisvogel --number-sections
|
||||
```
|
||||
|
||||
@ -289,7 +286,9 @@ pandoc example.md -o example.pdf --template eisvogel --number-sections
|
||||
|
||||
You can get syntax highlighting of delimited code blocks by using the LaTeX package listings with the option `--listings`. This example will produce the same syntax highlighting as in the example PDF.
|
||||
|
||||
``` bash
|
||||
```
|
||||
bash
|
||||
Copy code
|
||||
pandoc example.md -o example.pdf --template eisvogel --listings
|
||||
```
|
||||
|
||||
@ -297,19 +296,18 @@ pandoc example.md -o example.pdf --template eisvogel --listings
|
||||
|
||||
The following examples show [syntax highlighting of delimited code blocks](http://pandoc.org/MANUAL.html#syntax-highlighting) without using listings. To see a list of all the supported highlight styles, type `pandoc --list-highlight-styles`.
|
||||
|
||||
``` bash
|
||||
```
|
||||
bash
|
||||
Copy code
|
||||
pandoc example.md -o example.pdf --template eisvogel --highlight-style pygments
|
||||
```
|
||||
|
||||
``` bash
|
||||
bash
|
||||
Copy code
|
||||
pandoc example.md -o example.pdf --template eisvogel --highlight-style kate
|
||||
```
|
||||
|
||||
``` bash
|
||||
bash
|
||||
Copy code
|
||||
pandoc example.md -o example.pdf --template eisvogel --highlight-style espresso
|
||||
```
|
||||
|
||||
``` bash
|
||||
bash
|
||||
Copy code
|
||||
pandoc example.md -o example.pdf --template eisvogel --highlight-style tango
|
||||
```
|
||||
|
||||
@ -317,21 +315,27 @@ pandoc example.md -o example.pdf --template eisvogel --highlight-style tango
|
||||
|
||||
To produce a standalone LaTeX document for compiling with any LaTeX editor use `.tex` as an output file extension.
|
||||
|
||||
``` bash
|
||||
```
|
||||
bash
|
||||
Copy code
|
||||
pandoc example.md -o example.tex --template eisvogel
|
||||
```
|
||||
|
||||
### Changing the Document Language
|
||||
|
||||
The default language of this template is American English. The `lang` variable identifies the main language of the document, using a code according to [BCP 47](https://tools.ietf.org/html/bcp47) (e.g. `en` or `en-GB`). For an incomplete list of the supported language codes see [the documentation for the hyph-utf8 package (Section 2)](http://mirrors.ctan.org/language/hyph-utf8/doc/generic/hyph-utf8/hyph-utf8.pdf). The following example changes the language to British English:
|
||||
The default language of this template is American English. The `lang` variable identifies the main language of the document, using a code according to [BCP 47](https://tools.ietf.org/html/bcp47) (e.g. `en` or `en-GB`). For an incomplete list of the supported language codes see [the documentation for the hyph-utf8 package (Section 2)](http://mirrors.ctan.org/language/hyph-utf8/doc/generic/hyph-utf8/hyph-utf8.pdf). The following example changes the language to British English:
|
||||
|
||||
``` bash
|
||||
```
|
||||
bash
|
||||
Copy code
|
||||
pandoc example.md -o example.pdf --template eisvogel -V lang=en-GB
|
||||
```
|
||||
|
||||
The following example changes the language to German:
|
||||
|
||||
``` bash
|
||||
```
|
||||
bash
|
||||
Copy code
|
||||
pandoc example.md -o example.pdf --template eisvogel -V lang=de
|
||||
```
|
||||
|
||||
@ -346,37 +350,33 @@ There will be one blank page before each chapter because the template is two-sid
|
||||
### Example Images
|
||||
|
||||
| A green title page | A background image on the title page |
|
||||
| :----------------: | :----------------: |
|
||||
| [](examples/title-page-green/document.pdf) | [](examples/title-page-background/document.pdf) |
|
||||
| :----------------------------------------------------------: | :----------------------------------------------------------: |
|
||||
| [](https://chatgpt.com/c/examples/title-page-green/document.pdf) | [](https://chatgpt.com/c/examples/title-page-background/document.pdf) |
|
||||
|
||||
| images and tables | Code blocks styled without listings |
|
||||
| :---------------: | :---------------: |
|
||||
| [](examples/images-and-tables/document.pdf) | [](examples/code-blocks-without-listings/document.pdf) |
|
||||
| :----------------------------------------------------------: | :----------------------------------------------------------: |
|
||||
| [](https://chatgpt.com/c/examples/images-and-tables/document.pdf) | [](https://chatgpt.com/c/examples/code-blocks-without-listings/document.pdf) |
|
||||
|
||||
| A book | Code blocks styled with listings |
|
||||
| :----: | :----: |
|
||||
| [](examples/book/document.pdf) | [](examples/code-blocks-listings/document.pdf) |
|
||||
| :----------------------------------------------------------: | :----------------------------------------------------------: |
|
||||
| [](https://chatgpt.com/c/examples/book/document.pdf) | [](https://chatgpt.com/c/examples/code-blocks-listings/document.pdf) |
|
||||
|
||||
| A background images on all pages | CJK Support (when using XeLaTeX) |
|
||||
| :----: | :----: |
|
||||
| [](examples/page-background/document.pdf) | [](examples/language-japanese/document.pdf) |
|
||||
| :----------------------------------------------------------: | :----------------------------------------------------------: |
|
||||
| [](https://chatgpt.com/c/examples/page-background/document.pdf) | [](https://chatgpt.com/c/examples/language-japanese/document.pdf) |
|
||||
|
||||
## Common Errors / Issues
|
||||
|
||||
The following section lists common errors and their solutions when using the
|
||||
Eisvogel template.
|
||||
The following section lists common errors and their solutions when using the Eisvogel template.
|
||||
|
||||
### LaTeX Errors `Missing endcsname inserted` or `File x not found` when using `titlepage-background`, `logo`, or `titlepage-logo`.
|
||||
|
||||
``` latex
|
||||
Error producing PDF.
|
||||
```
|
||||
latexCopy codeError producing PDF.
|
||||
! Missing endcsname inserted.
|
||||
<to be read again>
|
||||
protect
|
||||
```
|
||||
|
||||
``` latex
|
||||
Error producing PDF.
|
||||
latexCopy codeError producing PDF.
|
||||
! Package pdftex.def Error: File `logo\T1\textunderscoreimage.pdf' not fou
|
||||
nd: using draft setting.
|
||||
|
||||
@ -384,27 +384,29 @@ See the pdftex.def package documentation for explanation.
|
||||
Type H <return> for immediate help.
|
||||
```
|
||||
|
||||
These errors occur when one includes a background image on the title page or a
|
||||
logo that has an underscore (`_`) in the filename.
|
||||
These errors occur when one includes a background image on the title page or a logo that has an underscore (`_`) in the filename.
|
||||
|
||||
A quick fix would be to replace all underscores in the filename of the image
|
||||
with a hyphen (`-`). If the background image is specified in your YAML front
|
||||
matter like so,
|
||||
A quick fix would be to replace all underscores in the filename of the image with a hyphen (`-`). If the background image is specified in your YAML front matter like so,
|
||||
|
||||
``` yaml
|
||||
```
|
||||
yaml
|
||||
Copy code
|
||||
titlepage-background: "background_image.pdf"
|
||||
```
|
||||
|
||||
you can advise pandoc to interpret this as LaTeX and include it in the document
|
||||
without parsing.
|
||||
you can advise pandoc to interpret this as LaTeX and include it in the document without parsing.
|
||||
|
||||
``` yaml
|
||||
```
|
||||
yaml
|
||||
Copy code
|
||||
titlepage-background: "`background_image.pdf`{=latex}"
|
||||
```
|
||||
|
||||
The same fix can be used for the logo image as well:
|
||||
|
||||
``` yaml
|
||||
```
|
||||
yaml
|
||||
Copy code
|
||||
logo: "`logo_image.pdf`{=latex}"
|
||||
```
|
||||
|
||||
@ -416,7 +418,7 @@ Corresponding issues:
|
||||
### LaTeX Error `Missing \begin{document}`
|
||||
|
||||
```
|
||||
! LaTeX Error: Missing \begin{document}.
|
||||
javascriptCopy code! LaTeX Error: Missing \begin{document}.
|
||||
|
||||
See the LaTeX manual or LaTeX Companion for explanation.
|
||||
Type H <return> for immediate help.
|
||||
@ -427,13 +429,12 @@ l.7 <
|
||||
! ==> Fatal error occurred, no output PDF file produced!
|
||||
```
|
||||
|
||||
This error indicates that you try to use some text file for conversion that is
|
||||
not the Eisvogel template. Please download the [latest Eisvogel template](https://github.com/Wandmalfarbe/pandoc-latex-template/releases/latest) from the releases page and start the conversion again.
|
||||
This error indicates that you try to use some text file for conversion that is not the Eisvogel template. Please download the [latest Eisvogel template](https://github.com/Wandmalfarbe/pandoc-latex-template/releases/latest) from the releases page and start the conversion again.
|
||||
|
||||
### LaTeX Error `auto expansion is only possible with scalable fonts`
|
||||
|
||||
``` latex
|
||||
Error producing PDF.
|
||||
```
|
||||
latexCopy codeError producing PDF.
|
||||
! pdfTeX error (font expansion): auto expansion is only possible with scalable
|
||||
fonts.
|
||||
\AtBegShi@Output ...ipout \box \AtBeginShipoutBox
|
||||
@ -441,8 +442,7 @@ fonts.
|
||||
l.643 \begin{lstlisting}
|
||||
```
|
||||
|
||||
This error likely occurs on Windows with MiKTeX installed. StackOverflow user
|
||||
[Krebto provided the following fix](https://tex.stackexchange.com/a/392467):
|
||||
This error likely occurs on Windows with MiKTeX installed. StackOverflow user [Krebto provided the following fix](https://tex.stackexchange.com/a/392467):
|
||||
|
||||
> To solve the problem navigate to `C:\Program Files\MiKTeX 2.9\miktex\bin\x64` and run `updmap.exe`. The program may seem as it hangs for a while, but its probably because it tries to update the whole font tree. This solved the problem for me. After re-compiling everything should work fine.
|
||||
|
||||
@ -452,20 +452,17 @@ Corresponding issue:
|
||||
|
||||
### LaTeX Error `cannot find image file`
|
||||
|
||||
``` latex
|
||||
Error producing PDF.
|
||||
```
|
||||
latexCopy codeError producing PDF.
|
||||
! error: (file "/tmp/tex2pdf.-be734e802ef6d0c3/""fdcfc29edcf252186f1b0a52f18f50
|
||||
43abaeb2d0".png) (pdf backend): cannot find image file '"/tmp/tex2pdf.-be734e802
|
||||
ef6d0c3/""fdcfc29edcf252186f1b0a52f18f5043abaeb2d0".png'
|
||||
! ==> Fatal error occurred, no output PDF file produced!
|
||||
```
|
||||
|
||||
In general this error means that LaTeX is unable to find the included image
|
||||
file. Please check all image references and file names for correctness.
|
||||
In general this error means that LaTeX is unable to find the included image file. Please check all image references and file names for correctness.
|
||||
|
||||
This error also occurs if you use an old version of Eisvogel with the package
|
||||
`grffile` and have an old LaTeX distribution installed. Please update Eisvogel
|
||||
and your LaTeX distribution.
|
||||
This error also occurs if you use an old version of Eisvogel with the package `grffile` and have an old LaTeX distribution installed. Please update Eisvogel and your LaTeX distribution.
|
||||
|
||||
Corresponding issues:
|
||||
|
||||
@ -478,4 +475,4 @@ Corresponding issues:
|
||||
|
||||
## License
|
||||
|
||||
This project is open source licensed under the BSD 3-Clause License. Please see the [LICENSE file](LICENSE) for more information.
|
||||
This project is open source licensed under the BSD 3-Clause License. Please see the [LICENSE file](https://chatgpt.com/c/LICENSE) for more information.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user