Assets
Location: inst/indiedown (folder)
Template assets are stored in a folder inst/indiedown.
This folder contains all the necessary information to customize your
markdown template. It can contain basic pandoc settings, additional
LaTeX settings and dynamic pandoc settings.
Basic Settings
Location: default.yaml (required)
default.yaml is the only required element of an
indiedown template. It specifies the default pandoc options used by your
template. To experiment with pandoc options, simply add them to the YAML
header of a standard R Markdown document.
Most relevant LaTeX options can be set as pandoc options. For
example, pandoc options allow you to set a customized font or a user
defined geometry. If possible always prefer Pandoc options instead of
LaTeX (covered below), as this will minimize unwanted interactions with
other options.
For a detailed description of all pandoc options, see the ‘Variables
for LaTeX’ section in the pandoc Manual.
default.yaml, as well as preamble.tex
supports substitution of the variable
<<indiedown_path>, which is explained below.
Additional LaTeX Settings
Location: preamble.tex (optional,
advanced)
Sometimes, pandoc options are just not enough. While pandoc allows
you to directly apply single LaTeX commands in the YAML header (using
headers-include), preamble.tex offers a more
convenient way to include LaTeX commands at the beginning of your
document.
To include commands, simply edit preamble.tex. Common
options set in preamble.tex are the modification of section
headings (e.g., \usepackage[small]{titlesec}), the
provision of the H float modifier
(\usepackage{float}), or the packages used by kableExtra.
For most customizations, it is recommended to turn off the default
LaTeX title page, using \renewcommand\maketitle{}. Creating
your own title page via LaTeX commands in the R Markdown script or by a
customized R function is a much easier and more flexible way to create a
customized title page.
Dynamic Settings
Location: pre_processor.R (optional,
advanced)
In a few cases, pandoc options should be set dynamically. E.g., the
geometry of a document should depend on whether it uses two columns or
just one. pre_processor.R allows you to dynamically modify
pandoc options, using plain R. See the example script for how to use
it.
Variable Substitution
default.yaml, as well as preamble.tex
supports substitution of the variable
<<indiedown_path>. Whenever you mention
<<indiedown_path> in one of your files, it will be
substituted by the path to the indiedown folder.
Main Font
The skeleton ships its main font in inst/indiedown/fonts
and loads it by path, via mainfont and
mainfontoptions in default.yaml. The output
therefore does not depend on the fonts installed on the system.
A format can prefer a font that it cannot ship, such as a licensed or
corporate font, with preferredmainfont and
preferredmainfontoptions in default.yaml. That
font is used if it is found, and so are all fonts that its options name,
such as BoldFont=. It is loaded from its font files, found
by file name in the folder named by the option
<package>.font_path and in the folders of the fonts
installed for the current user and for all users, by PostScript name in
the folder of the option, by name among the installed fonts, or by
PostScript name in the folder of the fonts installed for the current
user on Windows. Name all four faces in
preferredmainfontoptions, with BoldFont=,
ItalicFont= and BoldItalicFont=. A face that
is not named is taken from the files of the same family in the same
folder, by the weight and slant that fc-list lists or
systemfonts reads; without either, the font is loaded from its files
only if all faces are named. If it is not found, the shipped font is
used, and a message explains how to install fonts on the current
operating system. The message is shown at the start and at the end of
the render, and again in the same R session only if its advice changes.
Installed fonts are listed with fc-list, or with the
systemfonts package where fc-list is not available, such as
on macOS. systemfonts 1.3.0 or later also reads the PostScript names of
font files: list systemfonts (>= 1.3.0) in the
Suggests field of the template package.
A document can name another font in the mainfont field
of its YAML header, and a user can name one in the option
<package>.mainfont. The font can be the name of an
installed font or a font file. If it is not found, the preferred or
shipped font is used instead, with a message. The
mainfontoptions of the document apply to the named font, or
are appended to those of the preferred or shipped font if no font is
named.
Including Additional Assets
Most customized styles will include some additional assets, such as a
logo or a special font. Assets can be put into arbitrarily named
folders. To access the assets from default.yaml or
preamble.tex, simply use
<<indiedown_path>/res and the path will be
correctly resolved by indiedown.
LaTeX Generators
Indiedown packages use R functions to generate LaTeX code for
customization.
For most customizations, it is recommended to turn off the default
LaTeX title page, and create your own title page via LaTeX commands. The
basic repertory are the LaTeX commands \large,
\Large, \LARGE, \huge, etc, along
with vspace{1ex}, but all LaTeX trickery can be applied.
The LaTeX helper functions should be put in the R folder of
your package.