~toastal/sourcehut-asciidoc-renderer

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

refs

trunk
browse  log 

clone

read-only
https://git.sr.ht/~toastal/sourcehut-asciidoc-renderer
read/write
git@git.sr.ht:~toastal/sourcehut-asciidoc-renderer

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

sourcehut-asciidoc-renderer

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.

Caution

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

Usage

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

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

  outputs = { self, nixpkgs, sourcehut-asciidoc-renderer, ... }@inputs:
    let
      supportedSystems = [ "aarch64-linux" "x86_64-linux" ];
      forAllSystems = f: nixpkgs.lib.genAttrs supportedSystems (system: f system);
    in
    {
      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).

Development

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

License

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.

Funding

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