Organize with Yaml
How to Organize your Quarto Book
Quarto Books are combinations of multiple documents (chapters) into a single manuscript in one or more formats (HTML, PDF, Word Doc, etc). Our example below is based on the PAM_template_lab_manual:
index.qmd- the index.qmd file is in the root director for your project, and serves as the Home Page for a website. This file is mandatory.
_quarto.yml- the _quarto.yml is the configuration file for your project, and is also located in the root directory. The _quarto.yml provides information regarding overall formatting and structure of pages within the larger document.
README.md- Markdown file that serves as the readme for the github repository.
content folder- This folder contains the individual pages for your document. Alternative names for this folder are sometimes used, but we have found that the term ‘content’ is less confusing that frequently used alternatives. Here we recommend using this for consistency.
What is a YAML?
YAML is a human-readable data serialization language commonly used for configuration files. YAML works with multiple programming languages, and also allows users to add comments to their data (useful for documentation). YAML does require very specific indentation, mapping, etc. It is helpful to use a yaml checker to be sure your yaml does not have errors.
Quarto books/websites contain a _quarto.yml file, which is the website’s configuration file. It is essentially metadata for the website that includes the order that the pages/chapters will be in. This is where you organize your site. Here is a side-by-side example:
Learn more, here.
Modify YAML
Edit URLs- The website and repository links for the template need to be modified to point towards YOUR web/repo URLs
Change name and structure of Chapters. Does the chapter organization and naming fit your needs? Modify the contents component of the yaml to suit your needs, using ‘sections’ to identify identify sections with related chapters. Indentation and spacing are critical for yaml, so once you are ready, double-check your yaml by copy/paste entire yaml into a yamlchecker.
href: refers to the name of the relevant qmd file (located in the contents folder).
text: this is the text you will see on the sidebar of the web-book.
section: to identify sections that contain more than one chapter/pages within it. If you want the high level of the ‘section’ to contain information (when you click on it, a summary page appears), then point directly to a qmd file within the content folder. Otherwise, simply title the section.
You are now ready to create and modify your chapters/pages! Go to ‘Create Content’!