A hands-on project guide and platform feature gallery for authors, contributors, reviewers, and testers.
July 2026
LibreUni is a free learning platform built around plain content, static rendering, and interactive components. Lessons are written as MDX, courses are described with small JSON files, and the app turns that material into searchable course pages, lesson pages, exports, exercises, diagrams, and code labs.
The project is intentionally contributor-friendly. A useful change can be a new lesson, a better explanation, a fixed diagram, a more focused quiz, a clearer code sample, or an accessibility improvement.
Click the diagram to open the overlay. Large diagrams should keep their proportions, scale down when needed, and expand cleanly on demand.
| Area | Common files | Good contribution shape |
|---|---|---|
| Course metadata | apps/main/src/content/courses/*.json | Clear title, description, icon, color, image |
| Lesson content | apps/main/src/content/lessons/**.mdx | Focused lesson with examples, checks, and references |
| Interactive widgets | apps/main/src/components/* | Reusable feature with stable props |
| Build and tests | tests/**, tools/** | Verifies behavior without slowing normal authorship |
| Documentation | docs/**, README.md | Helps the next contributor make fewer guesses |
A good LibreUni contribution is small enough to review, rich enough to teach, and boring enough to maintain. Prefer one clear idea per lesson section. Use visual and interactive elements when they make the concept easier to understand, not as decoration.
A new contributor notices that a lesson explains state machines only in prose. They can either rewrite the entire UML course, add one focused diagram and quiz to the state-machine lesson, or start by changing the homepage layout.
This lesson is deliberately dense: it exists so contributors and testers can see the platform surface area in one place. It also works as a pattern catalog for new lessons.
Authors can write normal Markdown, tables, code fences, inline math such as , and display math:
type LessonFeature = "markdown" | "math" | "diagram" | "code" | "assessment";
const usefulFeature = (feature: LessonFeature) =>
feature === "diagram" ? "show structure" : "support understanding";
TikZ is useful for precise mathematical and conceptual drawings. This one is rendered at build time and participates in the same click-to-open overlay behavior as PlantUML.
The TikZ generation failed during build.
\draw[->, thick] (-0.3,0) -- (4.3,0) node[right] {$x$};
\draw[->, thick] (0,-0.3) -- (0,3.2) node[above] {$y$};
\draw[domain=0.25:4, smooth, variable=\x, blue, very thick] plot ({\x},{0.35*\x*\x});
\draw[dashed] (2,0) -- (2,1.4) -- (0,1.4);
\filldraw[blue] (2,1.4) circle (2pt);
\node[above right] at (2,1.4) {$f(x)=0.35x^2$};
\node[below] at (2,0) {$a$};
\node[left] at (0,1.4) {$f(a)$};
Python diagrams are rendered during the Astro build, cached, and displayed as normal lesson diagrams. This is the standard choice when an author wants Python to generate a stable visual explanation rather than an interactive lab.
Python can also generate SVG directly. This is useful for small custom diagrams where using a full plotting library would be heavier than the diagram itself.
The code runner is still useful when learners should experiment with code directly. It is not the standard way to publish stable diagrams, but it remains useful for exploration.
import from '../../../components/PlantUML.astro'; < code={\` Alice -> Bob: hello \`} />
The simplest contribution loop is: choose a narrow goal, edit locally, run the build, inspect the rendered page, and open a pull request with a clear summary. The loop is intentionally ordinary because ordinary workflows are easier to repeat.
The command runner can show examples for shells and compiled languages even when they are not executed in the browser. That makes it useful for tutorials about workflows.
A small commit message should say what changed and why it matters. It should have the first word in square brackets and indicate the type of change, such as [Add], [Fix], [Update], or [Refactor].
[Add] LibreUni contribution showcase course
Introduces a project-oriented course that demonstrates MDX authoring,
diagrams, code labs, quizzes, case studies, and local contribution flow.
A contributor has three ideas: add a typo fix, add a new lesson, and redesign the course cards. They are unrelated and each has different review risk.
LibreUni quality is not one test. It is a chain of signals: content reads cleanly, MDX compiles, diagrams render, interactive widgets hydrate, the layout works on mobile and desktop, and the lesson has a clear learning purpose.
For diagrams, the key quality question is simple: can a reader understand the structure without fighting the layout? The overlay exists so large diagrams can be inspected without squeezing text into unreadable shapes.
The TikZ generation failed during build.
\foreach \x/\label in {0/Content,2/Build,4/Preview,6/Review} {
\draw[rounded corners=4pt, fill=blue!8, draw=blue!60, thick] (\x,0) rectangle +(1.35,0.7);
\node at (\x + 0.675,0.35) {\small \label};
}
\draw[->, thick] (1.35,0.35) -- (2,0.35);
\draw[->, thick] (3.35,0.35) -- (4,0.35);
\draw[->, thick] (5.35,0.35) -- (6,0.35);
\draw[rounded corners=6pt, dashed, draw=green!60!black, thick] (-0.25,-0.25) rectangle (7.6,0.95);
\node[below] at (3.65,-0.25) {\small Every step should produce a useful signal};
The code runner can execute JavaScript snippets too. Use this for small algorithmic demonstrations where Python would be unnecessary.
This example visualizes a fictional quality dashboard. It is intentionally small, but it exercises the same runtime used by scientific and math lessons.
Use this checklist when reviewing a new lesson:
A lesson builds successfully, but one diagram is too dense, the quiz checks trivia instead of the learning goal, and a code sample prints twenty lines of unformatted output.