# asahilinux/docs: a hardware taxonomy split three ways, and a documentation site with no versions

> The Asahi Linux documentation repository is nine entries, one Python site generator, and a category scheme that separates the application processor, the SoC blocks around it, and the peripherals in the machine that are not the SoC. Its front page is 176 words and describes only that structure. The site is rebuilt on every commit and served from the default branch, so the device and platform information people search for most is published without a single version to cite.

**AsahiLinux/docs** — Asahi Linux documentation

- Repository: https://github.com/AsahiLinux/docs
- Website: http://asahilinux.org/docs/
- Stars: 2,302 · Forks: 109
- Language: HTML
- License: NOASSERTION
- Published: 2026-09-30 · Updated: 2026-09-30 · Language: en
- Canonical page: https://hysenlabs.com/projects/asahilinux-docs

## Hardware is split three ways, and only hardware is

The readme's whole contribution is a category scheme, and it is a careful one.

Six top level categories. Alternative operating system and distribution support. Vendor controlled firmware and firmware interfaces. Hardware. Material that applies across the Apple Silicon platform. Project administration, described as unrelated to hardware or software. And documentation for non firmware software.

Four of those six are single directories. Only hardware is subdivided, into four parts: application processor documentation, documentation relating to specific Mac models, hardware found in Apple Silicon Macs but not the SoC itself, and hardware blocks integrated into the SoCs.

That split is the useful part. It separates three levels that hardware documentation usually mashes together: the processor that runs the operating system, the specific machine it ships in, and the components attached to that machine which were not designed as part of the same chip. On Apple silicon that distinction is unavoidable, because a Mac model is a commercial name covering a processor generation plus a set of separately sourced parts, and a document that does not say which level it is at becomes unusable within a release.

The firmware and software boundary is stated just as plainly. Firmware means vendor controlled firmware and its interfaces. Software means everything that is not firmware. The platform category is the catch-all for anything true across the whole architecture.

One description is looser than the rest. The project category is for project admin documents and stuff unrelated to hardware or software, which is the only line in the scheme written as a note rather than a definition.

## Nine entries, and the site generator is a Python package

The repository root holds nine entries: a GitHub directory, a gitignore, a gitmodules file, a licence file, the readme, an artwork directory, the docs directory, an overrides directory and a configuration file.

There is no source tree, no build system of its own and no JavaScript. The site is generated by Zensical, and the readme is explicit about how to get it: it is installed as a Python package, and if your distribution does not package it, it is available through pip. The instruction for local work is one command:

```
$ zensical serve
```

That is the entire local build procedure. Install one package, run one command. The readme also acknowledges the gap that implies, by phrasing availability conditionally in the first place, which suggests the generator is recent enough not to be carried everywhere yet.

The two directories that are not documentation explain the rest. Overrides holds the theme layer, which is why the repository's detected primary language is HTML rather than Markdown: a docs repository is mostly Markdown, and the classifier is seeing the custom templates. Artwork holds images, and it is a top level directory with its own name, which tells you images are treated as a first-class part of the documentation rather than mixed into page folders.

The gitmodules file means at least one of those is pulled in from elsewhere rather than kept in this repository.

## The site is rebuilt on every commit, so there is no version to cite

One sentence covers the deployment model: the website is rebuilt by continuous integration on every commit and served through GitHub Pages.

There are no releases. So the documentation exists at exactly one address, containing whatever is on the default branch at the moment you fetch it.

For most projects that is a reasonable trade. Documentation moves with the code, a fix is live immediately, and nobody maintains a second copy. For this project the trade is worse, because of what the documentation is about.

The material is hardware and firmware documentation for Apple silicon, describing which components exist, how they are divided, and what interfaces are vendor controlled. That is the kind of content people cite. Someone writing a driver, a Linux port or a hardware bring-up document will link a specific page for a specific processor generation or a specific Mac model, and that link will resolve to whatever the page says on the day it is clicked.

It is worth noticing how the questions people arrive with line up with this. The four questions attached to this repository are all about what the project supports, which devices it runs on, whether it is stable, and what its current status is. Those are precisely the version-sensitive questions, and they are being answered by a documentation set that publishes no versions and keeps no archive.

None of that is a criticism of the readme, which never claims otherwise. It is a gap in what a rolling docs site can offer, and the fix is a versioned deployment alongside the rolling one rather than instead of it.

## The metadata records the documentation address as plain http

A small detail, and the only one on this page that is an outright inconsistency rather than a design choice.

The repository's recorded homepage is `http://asahilinux.org/docs/`. The readme's own first line links the same site as `https://asahilinux.org/docs/`.

So the address a repository listing shows and the address the documentation links to differ by scheme. Any tool that consumes repository metadata, which includes badges, directory listings, link previewers and anything that aggregates project homepages, will be working with the plain http form.

For a documentation site that is the wrong default in two ways. The first is that unencrypted navigation leaks the fact that someone is reading a page about a Linux distribution on Apple hardware, which is a small but real privacy question given what this project is. The second is that browsers and operating systems increasingly treat an http link as a downgrade worth warning about or refusing, so a user arriving from a directory listing may see a prompt before reaching a page that is perfectly capable of being served over TLS.

The fix is one field in repository settings. It is worth noting because the readme, which is the thing a maintainer edits when thinking about the project, already has the https form right.

## Conclusion

Use this repository if you are writing or reading Asahi Linux hardware documentation, because the category scheme is the contribution worth adopting: splitting hardware into the application processor, the SoC blocks integrated into it, and peripherals that exist in the Mac but not in the SoC is a distinction that most hardware documentation projects never make and that anyone working on this silicon has to. If you are looking for which Macs are supported or how mature the project is, this is the wrong repository, and no amount of reading its 176 word front page will help. Note the shape of what is published. There are no releases, the site is rebuilt by CI on every commit, and the result is served from the default branch, which means the device and platform material that people search for most has no version anyone can cite or link to. If you are writing something that will reference these pages, expect that reference to drift. Two smaller things to settle. The repository's licence field reads NOASSERTION while a licence file sits at the root, so establish the terms yourself before republishing documentation text or artwork, particularly since artwork is a top level directory of its own. And note that the whole toolchain is one Python package: if your distribution does not carry it, you install it with pip, which the page acknowledges in passing. That is a real simplification and also a single point of failure, so if you are building these docs inside an image or an air-gapped environment, pin it rather than relying on a distribution package appearing.

## FAQ

### Which devices are supported by Asahi Linux?

This repository does not answer that. It is the documentation repository for the project, and its readme describes only the structure of the documentation: six categories covering alternative distributions, vendor-controlled firmware, hardware, platform-wide material, project administration and non-firmware software. The supported device list belongs to the project's main site rather than to this repository.

### What is the current status of Asahi Linux?

Not answered here either. The repository contains no project status, no release history and no versioned documentation. It publishes no releases, and the page says the website is rebuilt by continuous integration on every commit and served through GitHub Pages, so what is published is whatever is on the default branch at that moment.

### Is Asahi Linux stable?

The documentation repository makes no maturity claim. It covers hardware and software material for Apple Silicon Macs and contains no statement about release channels, supported models or whether the project should be relied on for any particular purpose.

### How is the Asahi Linux documentation site built?

With Zensical, which is installed as a Python package. The readme says it is available through pip if your distribution does not package it, and that building the documentation locally for testing means installing Zensical and running zensical serve. The site is otherwise rebuilt by CI on every commit and served through GitHub Pages.

## Sources

- [AsahiLinux/docs on GitHub](https://github.com/AsahiLinux/docs)
- [Issues](https://github.com/AsahiLinux/docs/issues)
- [Project website](http://asahilinux.org/docs/)
- [README](https://github.com/AsahiLinux/docs/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/asahilinux-docs