```{#lst-chapterwritingguidelines-codeexample bash}
echo "SPAAM rules!"
```21 Chapter Writing Guidelines
You’re currently reading an introduction section of this page that demonstrates the standardised formatting that all chapters should follow to ensure consistency. You do not need a specific section header for ‘introduction’.
The main title of the page should go in the Markdown header at the top in the title section. Your name should also go, as well as a distinct bibliography file that you should generate and place bibtex references in. This file should be placed in the assets/references directory with exactly the same name as the name of this .qmd file but with the .bib extension. The end of the introduction should cover the ‘learning objectives’ of the chapter.
21.1 Language
The following language guidance is being displayed in a bullet point list using the hyphen character to indicate each item:
- All spelling should be in British English.
- Full stops should come after closing parentheses.
- For example (the full stop comes after the closing parenthesis).
- Voice should be in a ‘collective’ first person, as in ‘we’ or ‘our’.
21.2 Section Headings
All chapters should use section headings, up to a maximum of two sub-levels. The heading above corresponds to the second level.
Mandatory headings are
- The title (specified in the markdown header block, by default a highest level)
- Summary (second-level header, indicated by two
##) - References (second-level header, indicated by two
##)
21.2.1 Sub-section heading
This header here corresponds to the maximum heading depth you can get to. The purpose of this is to ensure that the document is easy to navigate and read. You will see therefore that we never go further than three numbers in header references, e.g. 20.03.1
21.3 Formatting
Generally, Quarto follows standard Markdown with some extra ‘syntax’ sugar. A Markdown cheatsheet can be found here.
21.3.1 General Markdown
One sentence per line. For example this is the first sentence. Here is the second sentence. This makes reviewing on GitHub easier.
New paragraphs should be separated by a blank line.
This would be a first sentence Then a second sentence Then a new paragraph. And so on.
To continue
- Italic formatting should be used with a single underscore
_and should be used for emphasis. - If required, Bold formatting should be used with double asterisks
**. This should not be used for emphasis. - URLs should be both hyperlinked around a relevant bit of text.
- For example, for visit the SPAAM Website this should be rendered visit the
[SPAAM Website](https://www.spaam-community.org/). - This is to make sure URLs in printed copies of the textbook are still visible.
- For example, for visit the SPAAM Website this should be rendered visit the
- Bullet point lists must start with a capital letter and not end with a full stop.
21.3.2 Notes and tips
For side nodes, tips, warnings, etc. you should Quarto callout blocks.
For example.
::: {.callout-warning}
We reserve some callout formatting for specific objects!
:::Gets rendered like this.
Warning
We reserve some callout formatting for specific objects!
See the Content for the reserved formatting. Note: I rendered that within-page link with [Content](#content) syntax, where #content is the name of the header in all lowercase and all punctiation replaced with -.
21.3.3 Code
Single backticks for inline code should only be used for single words such as tool names, e.g. samtools, file extensions such as .txt, or single paths <path>/<to>/<here>.
Any form of commands or code should be formatted as code in a syntax-named triple backtick block.
For example, this is a bash code block that has a whole command.
And gets rendered as like this.
echo "SPAAM rules!"SPAAM rules!If you wish to display large output from a code block, you should turn off the command execution printing in the code block itself, and use a collapsible callout block with a ‘Expand to see output’ title immediately after the code block itself that contains. The content of the output should also be in a triple backtick block, with the the default syntax specified.
echo "SPAAM rules!"
Expand see output
SPAAM rules!This was generated with
```{.bash eval=false}
echo "SPAAM rules!"
```
::: {.callout-note collapse="true"}
## Expand see output
```{.default eval=false}
SPAAM rules!
```
:::Additional guidance is as follows:
- Sentences prior a code block must end in a full stop and not a colon
- All code blocks must have a language specified
- Do not include leading
$or other prompt indicators at the beginning of code blocks- This makes copy pasting harder
- Any paths to should ideally be relative to the ‘working’ directory of that chapter
- This ensures portability of code between different systems and readers
- If paths require placeholders they should be in
<angle brackets> - Any code that should not actually be run by the user should be wrapped in a ‘warning’ callout block
- Optional ‘self-guided’ sections (i.e. sections that require user setup and would normally be already prepared for users by summer school organisers prior the summer school)
21.3.4 Figures
Figures should be included in the assets/images/chapters/<your-chapter>/ directory.
They can be inserted into a chapter either with typical markdown syntax or with the HTML (e.g. for centering purposes).
Regardless of the method used, the image should be given a caption, and a quarto label with the fig prefix ({#fig-<chapternamewithnopunctiation>-<imageidwithnopunctuation>}) for referencing the figure in the text.
For example, the following.
{#fig-chapterwritingguidelines-jacket}Would be rendered as as follows.
It is important for the caption to be as descriptive as possible to account for accessibility reasons.
All figures should be referenced in the text using the quarto label, and without a leading ‘Figure’ (this is rendered for you) e.g,.
"@fig-chapterwritingguidelines-jacket shows an example figure"Gets rendered as:
“Figure Figure 21.1 shows an example figure”.
21.3.5 Tables
Much like figures, all markdown tables must have a caption and referenced in text. To copy the quarto documentation example.
| Default | Left | Right | Center |
|---------|:-----|------:|:------:|
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
| 1 | 1 | 1 | 1 |
: Demonstration of pipe table syntax {#tbl-chapterwritingguidelines-exampletable1}Gets rendered as in Table Table 21.1.
| Default | Left | Right | Center |
|---|---|---|---|
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
| 1 | 1 | 1 | 1 |
This also applies to code-block generated tables e.g. as in Table 21.2. For example the next code block (if wrapped in the triple-backticks with r syntax, not shown here).
#| label: tbl-chapterwritingguidelines-examplecodetable2
#| echo: false
#| results: 'asis'
#| tbl-cap: "Your caption goes here."
#| tbl-cap-location: top
library(tidyverse)
library(pander)
tibble(a = 1, b = 2) %>%
pandoc.table(., split.tables = Inf)
Gets rendered as follows.
| a | b |
|---|---|
| 1 | 2 |
21.4 Chapter Content
21.4.1 Questions and Exercises
The end of every main section of the chapter (e.g. every second-level header) should have a little ‘task’ or question to test the reader’s understanding of the content.
These should be formatted as a Quarto callout block, with a renamed callout-tip class. This should be rendered in this ‘reserved’ call out block format.
::: {.callout-tip title="Question" appearance="simple"}
Your question(s) goes here.
:::
::: {.callout-note collapse="true" title="Answer"}
The answer(s) goes here, in a by-default 'hidden' block the reader can open to view.
:::Gets rendered as
Question
Your question(s) goes here.
Answer
The answer(s) goes here, in a by-default ‘hidden’ block the reader can open to view.
21.4.2 Data
There should be no data for practical tasks used on the chapter within the website repository.
All data should be be on Zenodo, or DOI-citable repository, and linked to from the chapter. Institutional Nextcloud or other cloud storage solutions are not acceptable for data storage. In most cases this will be stored for you by the course coorindator.
21.5 Bibliography
Each chapters that use citations must have a ‘References’ header as the last line of the document.
Citations can be specified in the text using the [@citation_key] syntax. This will automatically format the in text citation with parentheses. You should not use ‘free text’ or write manual citations. The references and keys themselves should be stored in the .bib (bibtex) file that you have created and specified in the markdown header of the page.
For example this textbook is Fellows Yates and Warinner (2024), or we really like AncientMetagenomeDir (Fellows Yates et al. 2021). For more citation styles please see the Quarto documentation. All references made in text will be by default rendered at the end of the document under the References header.
21.6 Summary
All chapters should have a summary section at the end. This should:
- Summarise the key points of the chaper
- Summarise the main takeaway points the chapter
- Should ideally be summarised in a few bullet points
21.7 References
Fellows Yates, James A, Aida Andrades Valtueña, Åshild J Vågene, Becky Cribdon, Irina M Velsko, Maxime Borry, Miriam J Bravo-Lopez, et al. 2021. “Community-Curated and Standardised Metadata of Published Ancient Metagenomic Samples with AncientMetagenomeDir.” Scientific Data 8 (1): 31. https://doi.org/10.1038/s41597-021-00816-y.
Fellows Yates, James A, and Christina Warinner. 2024. “Introduction to Ancient Metagenomics.” https://www.spaam-community.org/intro-to-ancient-metagenomics-book/.