docs/fix-links: init

The README/CONTRIBUTING files are authored with GitHub in mind, but we
want to re-use them for the docs website.

Replace the existing simple substitution with a pandoc AST-based filter.

Author: MattSturgeon

docs/fix-links/default.nix

@@ -0,0 +1,33 @@
+{
+  lib,
+  runCommand,
+  pandoc,
+  githubUrl ? "https://github.com/nix-community/nixvim/blob/main/",
+  docsUrl ? "https://nix-community.github.io/nixvim/",
+}:
+src:
+runCommand (src.name or (builtins.baseNameOf src))
+  {
+    inherit src;
+    bindings =
+      lib.generators.toLua
+        {
+          asBindings = true;
+        }
+        {
+          inherit githubUrl docsUrl;
+        };
+    filter = ./filter.lua;
+    nativeBuildInputs = [ pandoc ];
+  }
+  ''
+    echo "$bindings" > filter.lua
+    cat $filter >> filter.lua
+
+    pandoc \
+        --output $out \
+        --from markdown \
+        --to markdown-raw_attribute \
+        --lua-filter filter.lua \
+        $src
+  ''

docs/fix-links/filter.lua

@@ -0,0 +1,40 @@
+local len = pandoc.text.len
+local sub = pandoc.text.sub
+
+-- True if str starts with prefix
+local function hasPrefix(prefix, str)
+	local pfxLen = len(prefix)
+	local strLen = len(str)
+	if pfxLen == strLen then
+		return prefix == str
+	end
+	if pfxLen < strLen then
+		return prefix == sub(str, 1, pfxLen)
+	end
+	return false
+end
+
+function Link(link)
+	local target = link.target
+	-- Check for relative links
+	-- TODO: handle ../
+	if hasPrefix("./", target) then
+		link.target = githubUrl .. sub(target, 3)
+		return link
+	end
+	if not hasPrefix("https://", target) then
+		link.target = githubUrl .. target
+		return link
+	end
+
+	-- Check for absolute links, pointing to the docs website
+	if docsUrl == target then
+		link.target = "."
+		return link
+	end
+	if hasPrefix(docsUrl, target) then
+		local i = len(docsUrl) + 1
+		link.target = sub(target, i)
+		return link
+	end
+end

docs/mdbook/default.nix

@@ -317,7 +317,6 @@ pkgs.stdenv.mkDerivation (finalAttrs: {
     fileset = lib.fileset.unions [
       ../user-guide
       ../platforms
-      ../../CONTRIBUTING.md
       (lib.fileset.fileFilter (
         { type, hasExt, ... }:
         type == "regular"
@@ -330,6 +329,8 @@ pkgs.stdenv.mkDerivation (finalAttrs: {
     ];
   };
 
+  contributing = finalAttrs.passthru.fix-links ../../CONTRIBUTING.md;
+
   buildPhase = ''
     dest=$out/share/doc
     mkdir -p $dest
@@ -339,6 +340,9 @@ pkgs.stdenv.mkDerivation (finalAttrs: {
     mv ./docs/* ./ && rmdir ./docs
     mv ./mdbook/* ./ && rmdir ./mdbook
 
+    # Copy the contributing file
+    cp $contributing ./CONTRIBUTING.md
+
     # Copy the generated MD docs into the build directory
     bash -e ${finalAttrs.passthru.copy-docs}
 
@@ -382,21 +386,22 @@ pkgs.stdenv.mkDerivation (finalAttrs: {
     ;
 
   passthru = {
+    fix-links = callPackage ../fix-links {
+      # FIXME: determine values from availableVersions & baseHref
+      docsUrl = "https://nix-community.github.io/nixvim/";
+      githubUrl = "https://github.com/nix-community/nixvim/blob/main/";
+    };
     copy-docs = pkgs.writeShellScript "copy-docs" docs.commands;
     readme =
       runCommand "readme"
         {
           start = "<!-- START DOCS -->";
           end = "<!-- STOP DOCS -->";
-          baseurl = "https://nix-community.github.io/nixvim/";
-          src = ../../README.md;
+          src = finalAttrs.passthru.fix-links ../../README.md;
         }
         ''
           # extract relevant section of the README
           sed -n "/$start/,/$end/p" $src > $out
-          # replace absolute links
-          substituteInPlace $out --replace-quiet "$baseurl" "./"
-          # TODO: replace .html with .md
         '';
     search = search.override {
       baseHref = finalAttrs.baseHref + "search/";