janosh/diagrams: A Source-Only Gallery of 119 Physics, Chemistry and ML Figures
Diagrams of concepts in physics/chemistry/ML
At a glance
- What is it?
- A Typst-and-LaTeX figure collection that ships source code rather than finished images. It is useful if you want to edit someone else's diagram, and awkward if you want a maintained library or a stable API.
- Who is it for?
- Adopt it if you need an editable starting point for a figure in physics, chemistry or machine learning and you are comfortable reading someone else's Typst or TikZ. Do not adopt it as a plotting library, a CI rendering service or a source of publication-grade typography you have not inspected yourself.
- Can I use it commercially?
- Yes. MIT 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 2 days ago.
- What is it written in?
- Mainly Typst, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is not drawing, it is starting from a blank canvas
Most people who need a Bloch sphere, a branch cut plot or a convolutional filter diagram do not want to write one from scratch. They want an existing figure they can adjust. Search results give raster images with no source. Textbook figures are copyrighted. The gap this repository fills is narrow and real: it publishes the source for 119 diagrams in physics, chemistry and machine learning, under MIT, in two markup languages. The README states the split directly in its badges: 128 entries tagged as Typst, 80 tagged as LaTeX. Those numbers overlap because some diagrams exist in both formats, which is why the headline count of 119 is lower than either badge. The audience is a researcher or lecturer who already knows what a CeTZ or TikZ picture should look like and wants a working example to modify. It is not aimed at someone who wants to pass data in and get a chart out.
How the repository is laid out: one directory per diagram, three files deep
The README shows the submission convention plainly. Each diagram lives in its own folder under assets/, named after the diagram, and contains the drawing source plus a matching metadata file. The pattern visible in the table is assets/<slug>/<slug>.typ for Typst and assets/<slug>/<slug>.tex for LaTeX, with a corresponding .yml file holding the metadata. Rendered previews sit alongside as .avif, with a separate -dark.avif variant selected through a prefers-color-scheme media query, so each entry ships a light and a dark image. The README also shows that the table itself is generated: the diagram table is wrapped in an HTML comment marker, which implies a build step that rewrites the README from the assets directory rather than a hand-maintained list. The site at janosh.github.io/diagrams is described as supporting search, sort, opening in Overleaf and downloading PDF, SVG or PNG. That is the entire architecture: static source files, per-file metadata, a generated index, and a static front end. There is no runtime, no library to import, and no API to call.
Adding a diagram means matching a convention, not configuring a tool
The contribution path is spelled out in the README: submit a pull request with a .tex or .typ file and a corresponding metadata .yml file in the assets/ directory, then add yourself to citation.cff. That last step matters more than it looks. The repository carries a Zenodo DOI badge, so citations are a first-class concern and the citation file is the record of who contributed what. The metadata file is the mechanism that makes the site work: without it, a diagram has no title, no tags and no place in the generated table. This is a low-ceremony workflow, but it is also an all-or-nothing one. A diagram without metadata is invisible on the site. There is no schema documented in the material supplied here, so the practical way to learn the required keys is to read an existing .yml next to a diagram you like and copy its shape. Anyone expecting a documented ingest format will be disappointed; anyone comfortable reading examples will move quickly.
Two languages in one collection, and the maintenance that implies
The dual Typst and LaTeX coverage is the most distinctive thing about this repository and also the largest ongoing cost. The README badges count 128 Typst and 80 LaTeX entries, so the overlap is partial: many diagrams exist in only one language. That means the collection is not a translation layer and does not promise parity. If you need a diagram that only exists as TikZ, you are writing Typst from scratch or using LaTeX. Maintaining both formats for a single figure means two sources that can drift, and nothing in the material suggests an automated check that a .tex and its .typ sibling render the same picture. For a user this is a practical constraint: pick the format you can compile, and treat the other as a reference for geometry rather than a drop-in replacement. For the maintainer it is double the surface area for every diagram that gets both.
Where the collection stops being the right tool
This is a gallery, not a library. Nothing in the material describes a package you install, a function you call, or a way to feed a dataset into a figure. If your figure changes when your data changes, you need a plotting tool, and this repository will not help. The second limitation is compilation. Typst with CeTZ and LaTeX with TikZ are both real toolchains; using a source file means installing and running one of them, and the repository does not appear to ship a single-command build for a chosen diagram. The third is that figures are contributed by different authors over several years, with releases at v0.1.0 in December 2022 and v0.2.0 in January 2025. A collection that grows by pull request will vary in style, naming and level of commenting. You should expect to read each source file on its own terms rather than rely on uniform conventions. None of this is a defect in the project's stated purpose. It is a mismatch when the stated purpose is not what you need.
Compared with a general TikZ gallery
The obvious alternative is a broad TikZ example gallery, of which several exist and this project even carries tikz-gallery as a topic. The difference is curation and scope. A general gallery is organised around TeX techniques: how to draw an arc, how to shade a region, how to position nodes. This repository is organised around scientific subjects, with entries like Angular Momentum Quantization, Branch Cuts, Ball Tree and Autoencoder Architectures, and it carries a machine learning category that a general TeX gallery would not. The trade-off runs the other way too. A general gallery will have far more entries covering pure drawing mechanics, and its examples tend to be minimal and focused on one technique. Here you get a complete figure, which is more useful as a starting point and less useful as a lesson in how a specific CeTZ primitive behaves. If you are learning the drawing language, go to a technique-oriented gallery. If you need a figure about physics, this collection is the shorter path.
Licence, citation and the cost of keeping a fork
The repository is MIT licensed, which is permissive and permits reuse and modification with attribution, but the material supplied here does not state whether every contributed diagram carries the same terms or whether individual metadata files record separate licences. Check the .yml for the specific diagram before you reuse it in anything you publish; the top-level licence is not automatically the last word on a contributed file. The Zenodo DOI and citation.cff exist precisely so that reuse can be credited, and the README asks contributors to add themselves to citation.cff, which suggests citation is expected rather than optional. On maintenance: there is no dependency graph to keep current, because there is no library. The cost is the opposite kind. If you fork the repository to adapt a handful of diagrams, you inherit a directory structure, a generated README table and a metadata convention that exist to serve the site, not your fork. Copying the one .typ file you need into your own project is cheaper than tracking upstream, and the MIT terms allow exactly that.
Editorial conclusion
Adopt it if you need an editable starting point for a figure in physics, chemistry or machine learning and you are comfortable reading someone else's Typst or TikZ. Do not adopt it as a plotting library, a CI rendering service or a source of publication-grade typography you have not inspected yourself. Before you commit, clone the repository, open the .typ and .tex file for the specific diagram you want, check the .yml beside it for the licence and author fields, and confirm the site's Overleaf link actually opens for that entry.
Community notes