Elixir School: A Community-Maintained Curriculum for Learning Elixir

What Elixir School Is and How the Repository Is Organized

Elixir School is the content backend for elixirschool.com, the site that publishes free Elixir programming lessons. The repository holds only the lessons and blog posts; the website code lives in a separate companion repository, elixirschool/school_house, which uses Phoenix and NimblePublisher. NimblePublisher is a publishing engine that renders Markdown content with page metadata parsed from Elixir map literals at the top of each file.

The repository's directory structure reflects its purpose as a content store. Lessons live in the lessons/ directory, organized by language code. Blog posts live in posts/ and follow a filename pattern of YYYY-MM-DD-name-separated-with-hyphens.md. A bin/ directory contains utility scripts including the translation version report. Images are stored under images/. Additional directories hold conference-related content, podcast notes, and a glossary.

The primary language is listed as Elixir because the metadata at the top of each lesson is written as Elixir code, even though the lesson text itself is Markdown prose.

The Lesson Content and What It Covers

The lessons directory holds content in multiple spoken languages, with English as the source. Topics covered by the site include Elixir basics, collections, pattern matching, modules, processes, OTP, testing, and more advanced topics such as metaprogramming. The repository does not document the full lesson list in the README, but the CONTRIBUTING.md and wiki style guide govern how each lesson must be written.

Blog posts published through the repository follow a metadata format that specifies the author's name and GitHub link, relevant tags, a date, a title, and an excerpt. The date is written using Elixir's ~D[] sigil format, which is specific to the Phoenix/NimblePublisher rendering pipeline:

%{
  author: "Author Name",
  author_link: "https://github.com/author_github_account",
  tags: ["phoenix"],
  date: ~D[YYYY-MM-DD],
  title: "Full Article Title",
  excerpt: """
  Article short preview text
  """
}
---

This metadata format distinguishes Elixir School from markdown-only static site repositories: content authors need to be comfortable with Elixir map syntax even if they are not writing Elixir code in the lessons themselves.

Translating a Lesson and Using the Version Report

Elixir School supports lessons in multiple languages. Each language has a folder under lessons/ matching its language code. To translate a lesson, a contributor copies the English source file to the appropriate language folder and translates the prose. The metadata must be preserved, with the version field set to the original English version number, and the title and excerpt translated.

The version report script helps translators identify which lessons need attention:

elixir bin/version_report.exs

Filter by language code or severity:

elixir bin/version_report.exs --lang ja,es
elixir bin/version_report.exs --severity major,missing

The severity filter makes the script especially practical: a translator can focus on missing lessons first, then on major updates, before spending time on minor differences. This tooling is a meaningful practical addition over repositories that offer no automated way to identify translation debt.

Translated lessons must include a version field matching the English source:

%{
  version: "1.0.0",
  title: "基本",
  excerpt: """
  基本についての短い説明。
  """
}
---

The version field allows the report script to compare the translation's version against the current English version and flag it as outdated when the source was updated.

Contributing Lessons and Blog Posts

The repository explicitly encourages feedback and participation. Contributions follow the process documented in CONTRIBUTING.md and must conform to the lesson style guide linked from the wiki. The README indicates the style guide should be read before submitting changes.

For blog posts, the workflow is: create the file in posts/ with the correct naming pattern, add the metadata block, write the post, and submit a pull request for review before publication. For lessons, the process is similar: copy from English, translate, and submit a pull request.

The repository includes a .claude/ directory and an AGENTS.md file, suggesting it has set up guidance for AI-assisted contributions. CLAUDE.md is also present, indicating configuration for Claude Code. This makes Elixir School one of the few content repositories that has invested in AI contribution tooling alongside its human contributor process.

What Elixir School Does Not Provide

Elixir School is not an API reference. It does not document every function in the standard library or in popular packages such as Phoenix or Ecto. For API-level documentation, HexDocs and the official Elixir documentation are the appropriate resources.

The site also does not offer interactive code execution in the browser. Lessons are static text with code examples; readers must have a local Elixir installation to run the examples. Running the website locally requires setting up the school_house repository separately, as the content repository alone does not serve a website.

The focus is breadth over depth for introductory and intermediate topics. Engineers who have finished the basics and need detailed guidance on, for example, OTP supervision trees or Elixir's macro system will find the lessons a useful starting point but will need to go beyond them to the official language documentation.

Elixir School vs. the Official Elixir Getting Started Guide

The official Elixir Getting Started guide at elixir-lang.org is maintained by the Elixir core team and tracks language changes closely. It is authoritative for syntax and standard library behavior. Elixir School is community-maintained and covers similar ground but offers multiple spoken language translations and a blog with real-world use case articles.

The practical difference is translation coverage and contribution model. Elixir School's version report tooling and multi-language lesson structure make it more accessible to non-English speakers than the official guide, which is primarily in English. For teams onboarding engineers in languages other than English, Elixir School's translated content and clear contribution path for new translations offer something the official guide does not.

For accuracy of language feature descriptions, the official guide takes precedence. Elixir School acknowledges this implicitly by telling readers to visit elixirschool.com rather than treating the repository as self-contained reference material.

Editorial conclusion

Elixir School suits engineers who want structured, community-maintained Elixir learning material and who may want to contribute lessons, correct errors, or add a translation. It is a poor substitute for hands-on project work or official Elixir documentation when you need an API reference. Translators should run the version report script before starting to verify which lessons are outdated before investing time in them. The last push was on 2026-09-04, confirming the repository is actively maintained.

Frequently asked questions

Official sources

1. elixirschool/elixirschool on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README