Sourcehut doesn't support AsciiDoc for documentation—only the feature-lacking Markdown; this Flake aims to solve this simply.
nix flake update
Fix permissions
nix flake update


browse  log 



You can also use your local clone with git send-email.


Markdown lacks many basic features—however SourceHut only supports Markdown and not a more robust lightweight markup language like AsciiDoc. The purpose of this project is to overcome the lack of AsciiDoc support by making an easy-to-import Nix flake to compile the Asciidoc document as well as massage out any additional incompatibilities with classes and styling between the two.


This will not mean you will have broader AsciiDoc support. There are mailing list topics where Drew DeVault expressed that he wants no support of anything other than Markdown—as a result people are making the same errors with Markdown as usual like:

Lacking features
  • reinventing admonitions (**BOLD**: caption, or worse, using <blockquotes> via > unsemantically)
  • HTML inlining <img>`s just to get attributes like `width / height on them or `<span>`s just to get a classname on an element
  • no definition lists or collapsible support (<dl>, <details>)
  • using h[1-6] headings instead of block headings above elements like lists and source code blocks
  • manually maintaining a table of contents and section numbers, instead of the tool generating it with :toc: and :sectnums:
  • poor typography with -- -> ' (c) instead of — → ’ © automatically converted for those averse to using unicode input in their documents
  • without imports, no ability to better organize documentation
  • static site generators needing to invent a Markdown incompatible front matter that renders as a broken table when AsciiDoc supports this kind of metadata in its document header without needing a separate parser and can still be used to build standalone documents


Add this project to your Flake inputs, and then it can render any AsciiDoc file to a SourceHut-compatible style.

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    sourcehut-asciidoc-renderer.url = "sourcehut:~toastal/sourcehut-asciidoc-renderer";

  outputs = { self, nixpkgs, sourcehut-asciidoc-renderer, ... }@inputs:
      supportedSystems = [ "aarch64-linux" "x86_64-linux" ];
      forAllSystems = f: nixpkgs.lib.genAttrs supportedSystems (system: f system);
      packages = forAllSystems (system: {
        readme = sourcehut-asciidoc-renderer.renderAsciiDoc {
          inherit system;
          baseDir = ./.; # used to resolve includes::[]
          sourceFile = ./README.adoc;

This will build README.adoc to $out/share/doc/README.html when built with nix build ".#readme". After which you can read the Setting a custom README docs from SourceHut to help you upload your own README. You can also check out the readme task in the .build.yml file for an example of how to POST a custom README (and other infomation about Nix + Cachix in builds.sr.ht).


The only requirement is that Nix is downloaded.

To get the development shell
$ nix develop
For automatic shell via direnv on cd
$ cp .envrc.example .envrc
$ direnv allow
Caching via Cachix
$ cachix use toastal


This project is licensed under GNU Lesser General Public License version 2.1 or later (LGPL-3.0) — see the COPYING.txt + COPYING.LESSER.txt files in this project for details.


If you want to make a small contribution to the maintanence of this & other projects.