Markdown to Docbook pandoc conversion loses information about language in fenced code block

[ryantm]

We are using Pandoc to convert our Markdown documentation to Docbook, and the fenced code blocks all get converted to have the language as bash like:

<programlisting language="bash">
environment.systemPackages = [
  rustc
  cargo
];
</programlisting>

I haven't looked into it yet, but it seems like a bug with Pandoc or with how we are configuring it.

cc @andir @jtojnar

[jtojnar]

Yeah, I am aware of this. Pandoc only supports languages that it has syntax highlighting for and Nix is not one of them. Also, unfortunately, KDE’s syntax highlighting lists nix as file extension for bash.

I have opened jgm/pandoc#7241 (now hopefully part of pandoc in Nixpkgs not yet, requires 2.14), which allows us to fix the issue for Nix:

diff --git a/doc/Makefile b/doc/Makefile
index 7affbb0bb51..fd1deaac711 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -92,6 +92,7 @@ functions/library/generated: doc-support/result
 	pandoc $^ -t docbook \
 		--extract-media=media \
 		--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
+		--syntax-definition=$(PANDOC_NIX_SYNTAX_DEFINITION) \
 		-f markdown+smart \
 	| cat  > $@
 
@@ -100,5 +101,6 @@ functions/library/generated: doc-support/result
 		--top-level-division=chapter \
 		--extract-media=media \
 		--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
+		--syntax-definition=$(PANDOC_NIX_SYNTAX_DEFINITION) \
 		-f markdown+smart \
 	| cat  > $@
diff --git a/doc/default.nix b/doc/default.nix
index 25389fa2da7..3916b383e88 100644
--- a/doc/default.nix
+++ b/doc/default.nix
@@ -19,6 +19,10 @@ in pkgs.stdenv.mkDerivation {
 
   makeFlags = [
     "PANDOC_LUA_FILTERS_DIR=${pkgs.pandoc-lua-filters}/share/pandoc/filters"
+    "PANDOC_NIX_SYNTAX_DEFINITION=${pkgs.fetchurl {
+      url = "https://gitlab.com/rycee/presentations/-/raw/da77a89576fe8eed2a8b4f73e29b31895d45c98f/2019-12-cph-nur/nix-syntax.xml";
+      sha256 = "4ITrkuxNI0jmTsBToMt7OKoRiZQevGlDMPZgjiJtvEw=";
+    }}"
   ];
 
   postPatch = ''

Though I remember there were other issues.

[jtojnar]

Another method would be sending https://gitlab.com/rycee/presentations/-/raw/da77a89576fe8eed2a8b4f73e29b31895d45c98f/2019-12-cph-nur/nix-syntax.xml upstream to KDE. And maybe removing nix from the list of file extensions for bash:

https://github.com/KDE/syntax-highlighting/blob/09d72d8a90824739062a43fdd61a1763a86f8f35/data/syntax/bash.xml#L42