Structure

You can organise the content folder as you wish, but ensure you agree and document a structural and naming scheme with your team. You must create one MyST file for each webpage of your module’s site. MyST files must have extension .md, which stands for Markdown, the original tagging format on which MyST is based.

Tip

Within the content folder, create one folder for each block of the module, with one sub-folder per week. Use numbered folder names for the blocks and weeks, as it gives a faster overview over the available structure, but do not number any files within those folders. Use informative filenames instead.

You must include an accessibility statement for your site.

In the content folder there must be a _toc.yaml file that defines the website’s table of contents (TOC), which is used to generate the site navigation. Don’t forget to update the TOC file when adding, renaming or moving content files or folders.

The website’s TOC is organised into chapters and sections:

• A chapter is a group of files (webpages) optional containing sections. The chapters are shown in the main navigation across the top of the page.

• A section is a group of files that are shown in the sidebar on the left and each section an contain sub-sections.

How the material is divided into chapters and sections will depend on the material. The recommendation is to use chapters to define the blocks and sections to define individual weeks and content within the weeks.

The TOC file looks as follows. All file paths are relative to the content folder. File names are given without the .md extension. This example uses numbers in file and folder names to show what each TOC entry corresponds to.

format: jb-book
root: index  # This states that file content/index.md has the home page content.
chapters:
  - file: block-01/index # Introduction to the block
    # Folder content/block-01 has two folders week-01 and week-02
    sections:
      # Folder content/block-01/week-01 has files index.md, unit-1.md, unit-2.md, unit-2-1.md, etc.
      - file: block-01/week-01/index  # Introduction to the week
        sections:
          - file: block-01/week-01/unit-1
          - file: block-01/week-01/unit-2
            sections:  # This allows sub-units to be structured in the sidebar
              - file: week-01/unit-2-1
              - file: week-01/unit-2-2
          - file: week-01/unit-3
      - file: block-01/week-02/index
        chapters:
          - file: block-01/week-02/unit-1

The TOC defines the structure of the site’s navigation, it does not define the URL structure of the website. The URL structure is defined by the folder structure.

Tip

It is recommended that in practice the TOC and folder structure within content mirror each other. This eases maintenance. The one exception to that is the accessibility statement, which must be placed directly in the content folder, but can be placed anywhere in the TOC.

Ensure your agree with your team a structuring and naming convention for the TOC and how it maps to the content structure.