Document Structure

A sample markdown file can be found here in the doc folder: https://github.com/wikiknights/cs-materials/blob/main/doc/sample-file.md

Right now, each document is written in a markdown file (making it both portable and easy to write). Information on markdown syntax can be found here. These markdown files are then converted to other formats via a build script. The primary tool used to convert is called pandoc, and it uses an extended version of markdown for this. This gives additional flexibility for documents where needed. Information on these extensions can be found here.

Metadata Blocks

Each file can have a metadata block at the top (in the form of YAML) that specifies the title of each the document and its author(s). (See https://pandoc.org/MANUAL.html#extension-yaml_metadata_block for more details.)

Note: Metadata blocks are not required in a document, but are recommended.

For example:

---
title: Document Title
author: John Smith
---

With multiple authors:

---
title: Document Title
author:
  - John Smith
  - Sally Mae
---

With special symbols, use quotation marks:

---
title: 'Document Title 2: Electric Boogaloo'
author: Danny Dorito
---

By default, a table of contents is added to the top of the page, but this can be disabled on a specific page by adding "toc: false" to a metadata block:

---
toc: false
---

Code Blocks with Line Numbers

Code blocks (indicated by 3 back-ticks) can have line numbers added to the final output if the numberLines class is added. Notice the change in syntax if more than one class attribute is applied to a code block. (See https://pandoc.org/MANUAL.html#extension-fenced_code_attributes for more details.)

For example:

``` c
printf("This code block will not have line numbers.\n");
```

``` {.c .numberLines}
printf("This code block will have line numbers.\n");
```

Numbered Lists (Automatic Renumbering)

When creating numbered lists of practice problems, use @. to number the lists. This allows new problems to be added later with automatic renumbering. (See https://pandoc.org/MANUAL.html#numbered-example-lists for more details.)

For example:

@. This is the first question.
@. This is the second question.
@. This is the third question.

Hide Headings from Table of Contents

To hide a heading from a page's table of contents, add the unlisted class to the heading. For example:

# My Heading {.unlisted}