Geʽez Learning Hub (ግዕዝ)

A free, Git-based knowledge base for learning Geʽez — the classical liturgical language of Ethiopia and Eritrea. Built to work entirely on GitHub (content, CI, and hosting), with no paid services required.

Site: https://<your-github-username>.github.io/learn_geez/ (once GitHub Pages is enabled — see Deployment below)

What's here

• Curated, structured learning resources (books, courses, dictionaries, audio, apps)
• Original explanations of grammar and vocabulary concepts
• Example primary texts with transliteration and translation
• Guided learning paths tying resources/concepts/texts together
• Everything is plain Markdown + YAML frontmatter — readable, diffable, and easy for both humans and AI tools to extend

See the live About page for the project's principles, or jump straight to Start Here if you're here to learn.

Repository structure

See ARCHITECTURE.md for the full design rationale. In short:

content/         Canonical content — every published page (resources, concepts,
                 texts, learning paths, and static pages) as Markdown with YAML
                 frontmatter. Deliberately named `content/`, not `docs/`, so it
                 stays independent of MkDocs (see ARCHITECTURE.md).
schemas/         JSON Schema definitions for each content type (resource,
                 concept, text, learning-path).
taxonomy/        Controlled vocabularies: categories/subcategories, levels,
                 languages, relation types. The source of truth content is validated against.
templates/       Starting-point Markdown files for adding new content.
scripts/         Content validation tooling (schema + taxonomy + Unicode checks)
                 and the graph exporter — all pure Python, no MkDocs dependency.
.github/         Issue/PR templates and GitHub Actions workflows
                 (content validation on PRs, build+deploy to GitHub Pages on merge).
mkdocs.yml       Site configuration: theme, navigation, plugins, search.
                 The only framework-specific file of consequence.

Content model

Four content types, each Markdown + YAML frontmatter, cross-linked by stable ids so the same resource can be discovered from multiple categories/concepts without ever being duplicated:

• Resource — a book, website, video, PDF, course, dictionary, app, etc.
• Concept — a linguistic/educational concept (e.g. verb roots, noun morphology).
• Text — a primary or secondary Geʽez text.
• Learning Path — an ordered sequence of concepts/resources/texts.

templates/ provides nine ready-to-copy starting files (the four above, plus vocabulary entry, grammar topic, course, dictionary/reference, and audio resource — pre-filled specializations of Resource/Concept for common shapes). See templates/README.md for the full field-by-field reference and controlled values. Full schemas: schemas/. Controlled vocabularies: taxonomy/.

Local development

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

mkdocs serve          # local preview at http://127.0.0.1:8000
python scripts/validate_content.py     # schema + taxonomy validation
python scripts/check_geez_unicode.py   # Unicode integrity checks
mkdocs build --strict                  # production build, fails on broken links/nav

Deployment

Deployment is automatic via .github/workflows/deploy.yml on every push to main, using GitHub's native Pages Actions (no gh-pages branch, no external service). To enable it on a new fork/repo:

1. In the repo's Settings → Pages, set Source to "GitHub Actions."
2. Update the placeholder <your-github-username> references in mkdocs.yml, README.md, and content/*.md to your actual GitHub username/org.
3. Push to main — the deploy workflow builds and publishes the site.

Every push/PR also runs .github/workflows/validate.yml, which validates all content frontmatter and fails CI on schema violations, unknown taxonomy values, broken cross-references, or Unicode issues.

Contributing

See CONTRIBUTING.md — corrections, new resources, new explanations, and translation review are all welcome. Please read the ground rules there first: content must be honestly labeled with verification_status, and copyrighted material must never be redistributed (link to legitimate sources instead).

License

• Code, scripts, schemas, and templates: MIT.
• Original written content under content/: CC BY-SA 4.0.
• Linked third-party resources remain under their own original copyright and are not redistributed here.