Chapters

The chapters application (see What is an Application?) is the main focus of the CS Field Guide website, as it contains the majority of educational material for the project.

Chapters Overview

The application is made up of chapters and each chapter is broken down into sections.

Chapters Content Directory

The content directory for the chapters application contains

  • a directory for each language in which content exists, named using the Django locale code. This directory contains content Markdown files.
  • a special structure directory which contains all configuration YAML files

Content Files

There are 2 different types of files used for adding content to the CS Field Guide:

  • Content Markdown files
  • YAML configuration files

All files live inside the chapters/content directory. Content Markdown files are unique for each translation language, and are stored in a directory tree specific to that language. This directory is named using the languages Django locale code (for example: en or de). Configuration files are shared amongst all languages, because the content structure is the same for all languages. These files live under a special structure directory.

As a simple rule, structure files situated inside the structure directory contain no text a website user will see. Any user-facing text lives in a Markdown file inside the locale specific directories.

Configuration Files

This section details configuration files within the content/structure directory. These files are in YAML format. If you are not familiar with YAML, see Understanding Configuration Files.

The diagram below shows an example of YAML file locations for the content/structure/ language directory, where:

  • Blue is directories.
  • Red is YAML configuration files.
├── algorithms/
│   ├── sections/
│   │   └── sections.yaml
│   └── algorithms.yaml
├── artificial-intelligence/
│   ├── sections/
│   │   └── sections.yaml
│   └── artificial-intelligence.yaml
└── structure.yaml

In the following sections, each configuration file is explained in more detail.

Note

  • Some of the keys (What is a Key?) have angle brackets around them, <like so>. This means that they are variables and you can call them whatever you like in your configuration file (without the angle brackets). Key names should be consistent, i.e every instance of <chapter-key> should be replaced with the exact same key.

Application Structure Configuration File

  • File Name: structure.yaml
  • Location: chapters/content/structure/
  • Purpose: Defines the structure and location of all the different chapters.
  • Required Fields:
    • chapters: A dictionary of chapters, where each key is a chapter.
      • Required Fields:
        • <chapter-key>: The key for a chapter.
          • Required Fields:
            • chapter-number: The number order for this chapter.
  • Optional Fields:
    • glossary-folder: The name of the glossary folder.

A complete chapter application structure file with multiple chapters may look like the following:

chapters:
  introduction:
    chapter-number: 1
  algorithms:
    chapter-number: 2
glossary-folder: glossary

Chapter Configuration File

  • File Name: <chapter-key>.yaml
  • Location: chapters/content/structure/<chapter-key>/
  • Referenced in: chapters/content/structure/structure.yaml
  • Purpose: Defines the attributes for a particular chapter.
  • Required fields:
    • icon: File path to the icon for the chapter. Icons must be SVG files.
    • sections: File path to the configuration files for sections in the chapter.
  • Optional fields:
    • video: URL for the video that appears at the very beginning of the chapter introduction page.

A complete chapter structure file may look like the following:

icon: svg/introduction-icon.svg
sections: sections/sections.yaml

Chapter Sections Configuration File

  • File Name: sections.yaml
  • Location: chapters/content/structure/<chapter-key>/sections/
  • Referenced in: chapters/content/structure/<chapter-key>/<chapter-key>.yaml
  • Purpose: Specifiy sections for a chapter and their relative order.
  • Required Fields:
    • <section-key>: Key for the section.
      • Required Fields:
        • section-number: Number order for the section in the chapter.

A complete chapter application structure file with multiple chapters may look like the following:

introduction-for-teachers:
  section-number: 1

further-reading:
  section-number: 2