My overall advice would be to start simple and build your way up. As of right now, you are rendering your book to 4 different formats, gitbook, HTML, PDF, and Word. It will be really challenging to make all four outputs look and feel the same, so unless it is critical to have every format, I would start with one format and add more as required.
To take a step back, YAML is its own "language" and its core principle is that white-space/indentation matters. So any indented text is a child of the non-indented text above it. Think of these as arguments to functions.
There is a lot to unpack here, so I will try do it in steps:
The text below uses the default gitbook settings. Nothing special here.
These are the details for rendering to an HTML document (one single document). The above gitbook is actually HTML also, but with a different look (document split into chapters). Rendering to both is probably redundant and one could be removed. If you prefer this type of format, you may consider
bookdown::html_book() instead of
toc_float are just enabling the table of contents and allowing the TOC to float alongside the document as your scroll.
Everything below corresponds to the PDF version and its settings. The
book is a specific LaTeX format, like the
article class commonly used. Most of these settings are straightforward (table of contents, no template), but the
includes argument passes in two LaTeX files which probably contain some custom formatting code, some of which goes in the LaTeX preamble (
preamble.tex) and some which goes at the beginning of the book (before the body). These files are custom and presumably supplied by you.
This is your Word document specification, not much special going on here, just adding footnote support and to include figure captions and table of contents.
Pretty sure most of these settings are being ignored currently, as they are mostly arguments to a specific format but they aren't being passed to the format properly since they need to be indented below the the relevant output format in your
output section. I could be wrong though. Theme is an HTML-specific configuration setting.
fontsize only applies to PDF format (maybe Word too), I believe. Highlight defines a syntax/code highlighter, the figure options specify default sizes and whether captions are included.
fontsize: 12pt #What font is this setting for?
These are fine. The first option means your citations will be hyperlinked to their entry in the bibliography. You have presumably provided a
.bib file containing the possible documents to cite, and a CSL file is just an XML way of describing how to format the citations in-text and in the bibliography.
I think your APA
biblio-style is probably being ignored since you are using CSL instead.
biblio-style only applies to PDF anyway, I think, and only if you are using
biblatex for LaTeX citations. Probably can be removed without issue. Since pandoc handles the citations using
pandoc-citeproc, the other citation settings should apply to all output formats
classoption is related to the
documentclass specified much higher in your YAML. It specifies the
onside option for the
book document class for PDF format. The
always_allow_html option makes it so when you have HTML content (such as a widget) that it will play nicely with Word and PDF format documents, which cannot handle interactive content.