Your first repository

Each course is a git repository. It lives on GitHub, GitLab, Codeberg, or a Forgejo or Gitea server of your own. A learner adds it to Stemin by its address, and the app fetches the files and compiles them on the device. So the repository is the whole course, and you own it. A push reaches the learners at their next refresh, and a branch or a tag gives a version.

Most courses start with an AI. You ask it for a course in the Stemin format, run the checker on what it writes, and push the result. The first section shows the request. The rest of this page builds a small repository by hand, so that you know what the AI writes: one domain, one section, one topic and one deck, with two cards and one flashcard.

Ask an AI to write it

Paste this into any AI that can read a web page, and change the subject. The AI writes the course as a git repository:

Write a Stemin course that teaches me linear algebra. The format is at
https://stemin.app/docs.md. Run github.com/stemin-app/stemin-checker
on it and fix what it finds.

https://stemin.app/docs.md holds all of these pages in one Markdown file, so the AI reads the whole format from one address. If the AI cannot run programs, run the checker yourself (Check your repository) and give it the faults to fix. Then push the repository (Publish and add to Stemin).

What you need

The files

Make these five files:

index.md
math/
├── index.md
└── alg/
    ├── index.md
    └── linears/
        ├── index.md
        └── solving.md

Each directory is a container, and each container has an index.md. The depth of a file sets its kind, so no file says what it is. The tree gives the full rules.

FileKindId
index.mdthe repository rootnone
math/index.mda domainmath
math/alg/index.mda sectionalg
math/alg/linears/index.mda topiclinears
math/alg/linears/solving.mda decksolving

The root

The root index.md says which format the repository uses, who wrote it, and what it is. Its order lists the domains.

---
format: 3.0.0
author: Alice Smith
description: Algebra from the first equation.
order: [math]
---

The domain

A domain is the thing a learner selects in the app. It must declare its language.

---
title: Mathematics
lang: en
order: [alg]
---

The section

A section groups topics.

---
title: Algebra
order: [linears]
---

The topic

A topic holds decks. The app shows a topic as a chapter in its menu.

---
title: Linear equations
order: [solving]
---

The deck

A deck teaches one concept. Its cards come first, one idea each. Its flashcard follows: a question, and an answer inside it.

---
title: Solving a linear equation
---

::: card
A *linear equation* in one unknown has the form $a x + b = 0$. Solve it by isolating the
unknown, undoing each operation in turn.
:::

::: card
Subtract 4 from both sides, then divide both sides by 2:

$$ 2x + 4 = 10 \implies 2x = 6 \implies x = 3 $$
:::

::: flashcard q1
Solve $3x - 6 = 9$ for $x$.

::: answer
$x = 5$. Add 6 to both sides, then divide by 3.
:::
:::

A block opens with ::: kind and closes with a line that holds only :::. The ::: answer block sits inside the ::: flashcard block, so the flashcard closes after the answer. The block grammar gives every block.

Check it

Run the checker in the root of the repository:

stemin check .

A valid repository gives one line:

INFO . is a valid content repository

A fault gives the file, the line where it knows one, and what to do:

ERROR ./math/alg/linears/index.md: `extra` is here and `order` does not list it: add it to `order`, or mark the file `draft: true`
ERROR 1 fault

Fix each fault and run the checker again.

Push it

Commit the files and push them to the host. The repository must be public.

git init -b main
git add .
git commit -m "A first deck"
git remote add origin https://github.com/alice/algebra.git
git push -u origin main

Add it in Stemin

  1. Open Stemin.
  2. Press Add on the welcome page, or the + in the header.
  3. Write the address of the repository in Repository address, for example github.com/alice/algebra.
  4. Wait while the app reads the repository. It shows your description: and a list in Branch or tag.
  5. Keep main.
  6. Keep Install on this device on.
  7. Press Add.

The form closes, and the import starts. The button of the repository, on the welcome page or in Repositories, shows each stage: Reading, Downloading, Compiling, Saving. On a device with no other domain, the domain then opens, and the learner sees the two cards of the deck.

If the import fails, the app shows The import failed. and every fault it found. Publish and add to Stemin lists the faults a learner can see.

Next