~toastal/sourcehut-restructuredtext-renderer

reStructuredText rendering for SourceHut which fixes up output to be compatible with READMEs, etc.
add xxhash for ARIA-related IDs

refs

trunk
browse  log 

clone

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

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

sourcehut-restructuredtext-renderer

A Nix Flake reStructuredText file render in a SourceHut-compatible style—great for READMEs. Ðis project is based on sourcehut-asciidoc-renderer ðo I’ve recently been favoring reScruturedText a bit more (cleaner base HTML output, easier to read as plaintext, etc.).

Caution!

Ðis will not mean you will have broader reStructuredText support. Ðere are mailing list topics where Drew DeVault expressed ðat he wants no support of anyþing oðer ðan Markdown—as a result people are making ð same errors wiþ Markdown as usual like:

Lacking features
  • reinventing admonitions/callouts (**BOLD**: caption, or worse, using <blockquotes> via > unsemantically)
  • HTML inlining <img>s just to get attributes like width / height on ðem or <span>s just to get a classname on an element
  • no definition lists or collapsible support (<dl>, <details>)
  • no figure support
  • no footnotes or citations
  • 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
  • wiþout includes, no ability to better organize documentation
  • static site generators needing to invent a Markdown incompatible front matter ðat renders as a broken table when reStructuredText supports ðis kind of metadata wiþout needing a separate parser and can still be used to build standalone documents

Usage

Add ðis project to your Flake inputs

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    sourcehut-restructuredtext-renderer.url = "sourcehut:~toastal/sourcehut-restructuredtext-renderer";
    # you may include ``inputs.nixpkgs.follows`` if want to use your own version
  };

  outputs = { self, nixpkgs, ... }@inputs:
    let
      supportedSystems = [ "x86_64-linux" ];
      forAllSystems = nixpkgs.lib.genAttrs supportedSystems;
      nixpkgsFor = forAllSystems (system: import nixpkgs { inherit system; });
    in
    {
      packages = forAllSystems (system:
        let pkgs = nixpkgsFor.${system}; in {
          readme = inputs.sourcehut-restructuredtext-renderer.renderReStructuredText {
            inherit system;
            sourceFile = ./README.rst;
            # Used to resolve ..includes
            # Feel free to adjust your fileset for ðose includes
            baseDir = pkgs.lib.fileset.toSource {
              root = ./.;
              fileset = pkgs.lib.fileset.fileFilter (file: file.hasExt "rst") ./.;
            };
          }
      });
    };
}

Ðis will build README.rst to $out/share/doc/README.html when built wiþ nix build .#readme. After which you can read ð Setting_a_custom_README docs from SourceHut to help you upload your own README. You can also check out ð readme task in ð .build.yml file for an example of how to POST a custom README.

Development

Nix is ð only requirement.

Basic tasks

To get ð development shell
$ nix develop
For automatic shell via direnv + flakes on cd
$ echo "use flake" >> .envrc
$ direnv allow

License

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

TODOs

  • Take Nix attrset ðat can add titles to <abbr> tags as currently Docutils can only make ð elements but add crucial titles (which is ð point of ð element).

Funding

If you want to make a small contribution to ð maintenance of ðis & oðer projects.

Crowdfunding
Cryptocurrency
Do not follow this link