Elixir School: the lesson repository behind elixirschool.com, and how to translate it
The content behind Elixir School, the premier destination for people seeking to learn and master the Elixir programming language.
At a glance
- What is it?
- Elixir School is a Markdown lesson and blog repository, not a runnable website. What it contains, how the translation version report works, and where the project stops.
- Who is it for?
- Adopt it if you are writing or translating Elixir lessons and want the content to live in plain Markdown under version control, or if you want a worked example of a NimblePublisher content tree. Do not adopt it expecting a self-contained site: the README states that this repository only contains the lessons and blog posts, and that the website code and setup live in the school_house repository.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 72 days ago.
- What is it written in?
- Mainly Elixir, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- elixirschool/elixirschool3,675 ★ · +3
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| elixirschool/elixirschool | 3.7k | 3.7k |
3 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What the repository actually holds, and who it is for
Elixir School is the content behind the site at elixirschool.com. The README is explicit that "This repository only contains the lessons and blog posts hosted on Elixir School", and it points at the separate school_house repository for the code and setup needed to run the website locally. That single sentence defines the project's boundary, and it is the thing most people get wrong before cloning.
The top-level layout matches that claim. There is a lessons/ directory, a posts/ directory, plus conferences/, images/ and podcasts/. There is no application entry point in the listing, and no mix.exs is mentioned. What you get is Markdown, metadata blocks and a few scripts in bin/.
The audience is therefore narrow and specific. It is for people who want to write or translate Elixir teaching material and have it published on a site someone else operates. It is also a reasonable reference if you are building your own content pipeline on NimblePublisher and want to see how a real content tree is arranged, since the README names NimblePublisher as the publishing engine behind the site. If you want an application to run, this is not it.
How lessons and posts are structured: metadata block, then Markdown
Both content types use the same shape. A file opens with an Elixir map literal, then a line containing three hyphens, then the Markdown body. The README gives the lesson example as lessons/ja/basics/basics.md, where the map carries version, title and excerpt, and the excerpt itself is a heredoc string.
The version key is the load-bearing part. For a translated lesson, the README says version "should be set to the original English version". That is how the project tracks whether a translation has fallen behind: the translation declares which English revision it corresponds to, and the tooling compares that number against the current English file. Title and excerpt are translations of the originals, not free text you invent.
Blog posts use the same delimiter but a different map. The README lists author, author_link, tags, date, title and excerpt, with date written as an Elixir date sigil, ~D[YYYY-MM-DD]. Post filenames must follow the pattern YYYY-MM-DD-name-separated-with-hyphens.md, so the date appears twice: once in the filename and once in the metadata. Nothing in the README says which one wins if they disagree. That is a real gap, and my reading is that the metadata is what gets rendered, because that is the value the publishing engine parses, but the README does not state it.
The multilingual layout is a directory convention rather than a config file. Each language gets a folder under lessons/, so Japanese lessons sit in lessons/ja/ and the English originals sit alongside them. Adding a language means adding a directory, not registering it anywhere, which keeps contribution cheap and makes the version report the only place where the set of languages is discovered.
Installing nothing: how to make a first translation
There is no install step for this repository, because it is not an application. You need Elixir on your machine to run the scripts in bin/, and you need git to submit a pull request. The README does not give an Elixir version requirement, so if you hit a syntax error in a script that is the first thing to check.
Start by finding the work that needs doing for your language. The version report script is the entry point, and the README shows it taking a --lang flag with a comma-separated list:
elixir bin/version_report.exs --lang ja,esRun it against your own language code and you get the list of pages that are missing or outdated. The README also shows a --severity flag accepting major and missing, which you can combine with the language filter:
elixir bin/version_report.exs --severity major,missingThen copy the English file into your language folder and translate it. The metadata at the top is the part that must match the original, and the README's example for lessons/ja/basics/basics.md shows the version string carried over unchanged:
%{
version: "1.0.0",
title: "基本",
excerpt: """
基本についての短い説明。
"""
}
---What you should see after copying is a file whose version matches the English source, whose title and excerpt are in your language, and whose body is the translated Markdown. Submit it as a pull request. The README says changes are reviewed before publication and asks contributors to read the wiki lesson style guide first, so expect editorial feedback on wording rather than a merge on first push.
The version report is the only quality gate the README documents
Everything about keeping translations honest rests on bin/version_report.exs. That is a design choice with a clear upside: staleness becomes a number you can print, not a judgement call. A translator can see exactly which pages drifted and how badly, filtered down to major and missing, instead of reading every English file to spot changes.
The limitation is symmetrical. The script compares versions, so it only knows about pages where someone remembered to bump the version. If an English lesson is edited without its version changing, the report stays quiet and the translation silently diverges. The README does not describe any check that enforces version bumps, and it does not document a CI job that fails a pull request for a stale translation. The style guide lives in a GitHub wiki, outside the repository tree, so it cannot be reviewed in the same pull request as the lesson it governs.
There is a second gap worth naming. The README documents how to add a translation and how to add a post, but it does not document rollback, deprecation of a lesson, or what happens to a translation when the English original is deleted. If you are planning to contribute at volume, those are the questions to ask in an issue before you invest in a large batch.
Where it is the wrong tool, and what to use instead
If your goal is to run a documentation site for your own project, this repository is the wrong starting point. It has no website code, and the README redirects you to school_house for that. Cloning it and expecting a local server will not work.
The closer alternative for that job is ExDoc, which ships with Elixir tooling and generates HTML documentation from @moduledoc and @doc attributes attached to your source. The difference in approach is where the prose lives. ExDoc keeps documentation inside the code, so it moves when the code moves and a stale doc is at least adjacent to the function it describes. Elixir School keeps prose in standalone Markdown under lessons/, decoupled from any codebase, which is what makes translation and editorial review practical but also what makes staleness a tracking problem the version report has to solve.
If you are specifically building a Markdown publishing pipeline, the underlying engine named in the README, NimblePublisher, is the thing to read, and this repository is a working example of its content conventions rather than a library to depend on. If you want a general-purpose static site generator, nothing here applies; the metadata format is Elixir map literals, which only make sense inside an Elixir build.
Maintenance, licensing and the cost of keeping translations current
The repository is not archived, and the last push was on 2026-09-04. For a content repository that means the lesson tree is still receiving commits, which is consistent with an open contribution process and a hacktoberfest topic in the repository metadata.
The upgrade cost sits almost entirely with translators rather than with the code. The repository has no published GitHub releases, so there is no versioned artifact to track; the unit of change is a Markdown file. The recurring work is running the version report, picking up pages flagged major or missing, and updating the version string alongside the prose. That cost scales with the number of languages you maintain, not with the size of the English tree, which is why the --lang filter exists.
The project is licensed Apache-2.0, and the LICENSE file is at the repository root. For anyone translating lessons, the practical implication is that a translation is a derivative work distributed under the same licence, and the Apache-2.0 terms include attribution and notice requirements. That is a description of the licence text, not legal advice; if you plan to republish the lessons inside a paid product, read the LICENSE file yourself and get proper counsel rather than relying on a summary.
Editorial conclusion
Adopt it if you are writing or translating Elixir lessons and want the content to live in plain Markdown under version control, or if you want a worked example of a NimblePublisher content tree. Do not adopt it expecting a self-contained site: the README states that this repository only contains the lessons and blog posts, and that the website code and setup live in the school_house repository. Before opening a pull request, run elixir bin/version_report.exs --lang <your-lang> to confirm which pages are missing or outdated, and check the wiki lesson style guide the README points to, since the README does not document any automated check that enforces it.
Frequently asked questions
Is Elixir School the same as the Elixir programming language?
No. Elixir School is the content repository behind the elixirschool.com site, holding lessons and blog posts about Elixir. The README states that this repository only contains the lessons and blog posts hosted on Elixir School.
What exactly is Elixir School?
It is a Markdown content repository: lessons live under lessons/ with a metadata block at the top of each file, and posts live under posts/. The website itself is powered by Phoenix and NimblePublisher, with code and setup in the separate school_house repository.
Is Elixir School worth using for learning Elixir?
The repository is a content tree, so what you get is the lesson material rather than an application. The README directs readers to elixirschool.com for the lessons themselves, and the repository is where that material is written and translated.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/elixirschool-elixirschool)Star history chart for your README
[](https://hysenlabs.com/projects/elixirschool-elixirschool)Was this useful?