The root and the domain

The root index.md

Each repository has one index.md at its root. The app reads this file first, before the rest of the repository, to show the learner what the repository is.

---
format: 3.0.0
author: Alice Smith
description: Mathematics and physics, from first principles to exam practice.
order: [math, phy]
---

Text after the front matter is an error. Put notes for people in a README.md: the tree ignores it.

format:

The value is a semantic version with three numbers. This version of Stemin reads format 3. It accepts every minor and patch version of 3, for example 3.0.0 or 3.3.1, and it refuses every other major version. A repository in format 1 or 2 does not parse, and nothing converts it. To move a repository from format 2, write ::: flashcard for each ::: exercise in a deck and ::: question for each one in a checkpoint, then write format: 3.0.0.

The checker reports each problem:

ERROR ./index.md: `format:` must be a semantic version like `3.0.0`, and this repository declares none
ERROR ./index.md: `format:` must be a semantic version like `3.0.0`, and `3.0` has no patch
ERROR ./index.md: this repository targets format 2.0.0, and this build reads 3.x: update the app, or pin the repository to a release that speaks 2.0.0

The app checks format: when the learner writes the address, before it downloads anything else. A root without format: gives:

this repository declares no `format:`, so it is not a content repository

author:

The name of the person or the group that wrote the repository. A domain without its own author: takes this one. The app keeps the author with each domain. The interface does not show it today.

description:

One sentence about the repository. The app shows it in the add modal, under the address, and in the Install a repository list of the welcome page. Keep it short: the learner reads it before adding the repository.

order:

The ids of the domains, in order. The rules of order are in The tree.

The domain index.md

A domain is the thing a learner selects in the app. Each directory at the root is a domain.

---
title: Physics
lang: en
labels: { reference: Formula, references: Formulary, derivation: Proof, checkpoint: Exam, checkpoints: Exams }
order: [eam]
---

A domain must hold at least one deck:

ERROR ./math/index.md: this domain holds no deck, so it compiles to nothing: give it a section, a topic and a deck

lang:

One BCP 47 tag, for example en, pt-BR or zh-Hans. It declares the language the domain is written in. The learner never selects it. While the domain is open, the app sets the language of the content column to it, so a screen reader reads the content in that language. The tag does nothing else today.

The checker requires the field:

ERROR ./math/index.md: `lang:` is missing or malformed: a domain declares one BCP 47 tag, like `en`

The checker requires a value that is not empty. It does not test that the value is a valid BCP 47 tag.

labels:

The format uses generic words, because a repository can teach any subject. A domain can give the interface its own words:

labels:
  reference: Formula
  references: Formulary
  derivation: Proof
  checkpoint: Exam
  checkpoints: Exams

Each label is optional. A label that you do not set takes its default.

Today the interface reads two keys. references names the set of references of a section and of a topic. checkpoints names the row that opens the exams. The app keeps the other keys, so you can declare them now. A key that is not in the table is an error:

ERROR ./math/index.md: `formula` is not a label: the labels are domain, section, topic, deck, card, flashcard, question, solution, reference, references, derivation, checkpoint, checkpoints

A label changes only the text on the screen. It never changes an id, an address in the app, or the progress of a learner. So you can change a label at any time.

The section index.md

---
title: Algebra
tiers: [entrance, university]
order: [linears, quadratics]
---

The topic index.md

---
title: DC circuit analysis
tier: entrance
requires: [components]
order: [kirchhoff, dividers, mesh-analysis, nodal-analysis, sources, thevenin, superposition]
---

Tiers

A tier is a band of audience or of difficulty. The section declares its words in order, and each topic takes one:

# math/alg/index.md
tiers: [entrance, university]

# math/alg/linears/index.md
tier: entrance

The words are yours: entrance and university for exam practice, or operator and expert for a manual. A topic can leave out tier. A tier that is not in the tiers of its section is an error:

ERROR ./math/alg/linears/index.md: tier `graduate` is not in the section's `tiers`, [entrance, university]: use one of them, or add it there

The compile keeps both values, and no screen uses them today.

Languages and translations

A domain is written in one language. A course in another language is another domain: another directory, its own lang:, its own id and its own progress.

# phy-pt/index.md
---
title: Física
lang: pt-BR
order: [eam]
---

The other domain can sit in the same repository or in a different one. There are no language directories, no translation files and no fallback from one language to another. To translate a course, copy its domain and translate the copy.

The interface language is a separate thing. The app has its own strings for its buttons and menus, and it ships English only for now.