Filter update, documentation still missing

Author: jdutant

.editorconfig

@@ -23,3 +23,8 @@ max_line_length = 80
 # Text with 60 to 66 characters per line is said to be the easiest
 # to read.
 max_line_length = 66
+
+[*.qmd]
+# Text with 60 to 66 characters per line is said to be the easiest
+# to read.
+max_line_length = 66

.github/workflows/ci.yaml

@@ -17,8 +17,8 @@ on:
   # This way we will catch incompatible pandoc changes in a timely
   # manner.
   schedule:
-    # At 5:39am each Tuesday
-    - cron: '39 5 * * 2'
+    # At 3:47am each Thursday
+    - cron: '47 3 * * 4'
 
 jobs:
   test:
@@ -27,10 +27,9 @@ jobs:
       fail-fast: true
       matrix:
         pandoc:
-          - edge
+          #- edge # uncomment to catch errors faster
           - latest
-            # This should be the oldest version that's supported
-            # - 2.19.2
+          # - 2.19.2
 
     container:
       image: pandoc/core:${{ matrix.pandoc }}
@@ -43,4 +42,4 @@ jobs:
         run: apk add make
 
       - name: Test
-        run: make test
+        run: make test BUILD=false

.github/workflows/website.yml .github/workflows/doc.yml.github/workflows/website.yml renamed to .github/workflows/doc.yml

@@ -1,4 +1,4 @@
-name: Publish Website
+name: Publish Manual
 
 # Allow one concurrent deployment
 concurrency:
@@ -14,9 +14,13 @@ permissions:
 on:
   push:
     branches: ['main']
+    paths-ignore:
+      - 'README.md'
+      - LICENSE
+      - .editorconfig
 
 jobs:
-  website:
+  manual:
     runs-on: ubuntu-latest
     environment:
       name: github-pages
@@ -26,11 +30,15 @@ jobs:
         uses: actions/checkout@v4
       - name: Setup Pages
         uses: actions/configure-pages@v5
+      - name: Prepare custom pandoc container
+        run: |
+          docker build -t custom-pandoc -f .tools/Dockerfile .
       - name: Render Website
         run: |
           make -B website \
+            SOURCE_DIR="" \
             PANDOC="docker run --rm --volume $(pwd):/data \
-              --user $(id -u):$(id -g) pandoc/core:latest"
+              --user $(id -u):$(id -g) custom-pandoc"
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

.gitignore

@@ -1 +1,12 @@
+# Docs output
 /_site/
+
+# Quarto artefacts
+/example-quarto/*_files/
+/example-quarto/*.html
+/example-quarto/*.pdf
+/example-quarto/*.tex
+/.luarc.json
+
+# MacOS
+**/*.DS_Store

.tools/Dockerfile

@@ -0,0 +1,12 @@
+FROM pandoc/latex:latest
+
+# Uncomment the lines below to customize latex.
+# Specify here an archive TeXLive if the pandoc/latex image isn't
+# yet updated to the last version.
+#
+# RUN tlmgr option repository https://mirror.ctan.org/systems/texlive/tlnet \
+#     && tlmgr install \
+#     latex-package-1 \
+#     latex-package-2
+
+ENTRYPOINT [ "/usr/local/bin/pandoc" ]

.tools/anchorlinks.js

@@ -0,0 +1,38 @@
+/* anchorlinks.js: add anchor links before headers h2, h3
+*/
+document.addEventListener("DOMContentLoaded", function () {
+    const headers = document.querySelectorAll("h2, h3" );
+    var css_needed = false;
+
+    headers.forEach(header => {
+        if (header.id) {
+            css_needed = true
+            // create anchor
+            const anchor = document.createElement("a");
+            anchor.href = `#${header.id}`;
+            anchor.textContent = "#";
+            anchor.className = "header-anchor";
+            // insert after header
+            header.appendChild(anchor);
+        }
+    });
+
+    if (css_needed) {
+        const style = document.createElement("style");
+        style.appendChild(document.createTextNode(`
+            .header-anchor {
+                display: inline-block;
+                text-decoration: none;
+                margin-left: 8px;
+                font-size: 0.8em;
+                opacity: 0.5;
+            }
+            
+            .header-anchor:hover {
+                opacity: 1;
+                text-decoration: underline;
+            }
+        `));
+        document.head.appendChild(style);        
+    }
+});

.tools/anchorlinks.lua

@@ -0,0 +1,19 @@
+function Meta(meta)
+    ptype = pandoc.utils.type
+    if meta['header-includes'] then
+        head_inc = meta['header-includes']
+        if ptype(head_inc) == 'table' then
+            head_inc = pandoc.List:new(head_inc)
+        else
+            head_inc = pandoc.List:new{head_inc}
+        end
+    else
+        head_inc = pandoc.List:new{}
+    end
+    head_inc:insert(pandoc.RawBlock('html', 
+        '<script src=anchorlinks.js></script>'))
+    meta['header-includes'] = head_inc
+    return meta
+end
+
+

.tools/docs.lua

@@ -2,8 +2,16 @@ local path = require 'pandoc.path'
 local utils = require 'pandoc.utils'
 local stringify = utils.stringify
 
+local function log(msg)
+  io.stderr:write('[Docs.lua filter: ERROR] '..msg..'\n')
+end
+
 local function read_file (filename)
   local fh = io.open(filename)
+  if not fh then
+    log('Cannot read file '..filename..'.')
+    return
+  end
   local content = fh:read('*a')
   fh:close()
   return content
@@ -17,8 +25,11 @@ local formats_by_extension = {
   html = 'html',
 }
 
-local function sample_blocks (sample_file)
+local function sample_blocks(sample_file)
   local sample_content = read_file(sample_file)
+  if not sample_content then
+    return nil
+  end
   local extension = select(2, path.split_extension(sample_file)):sub(2)
   local format = formats_by_extension[extension] or extension
   local filename = path.filename(sample_file)
@@ -30,17 +41,16 @@ local function sample_blocks (sample_file)
   }
 end
 
-local function result_block_raw(result_file, format)
-  local result_content = read_file(result_file)
-
+local function result_block_raw(result_content, format)
   return pandoc.CodeBlock(result_content,
     pandoc.Attr('', {format, 'sample'})
   )
 end
 
 local function result_block_html(filename)
   local html = '<iframe width=100% height=720px '
-    ..'src="'..filename..'" sandbox>\n'
+    -- ..'src="'..filename..'" sandbox>\n'
+    ..'src="'..filename..'">\n' -- non-sandbox to display linked images
     ..'<p><a href="'..filename..'">Click to see file</a></p>\n'
     ..'</iframe>'
   return pandoc.RawBlock('html', html)
@@ -50,56 +60,69 @@ local function result_blocks(result_file)
   local extension = select(2, path.split_extension(result_file)):sub(2)
   local format = formats_by_extension[extension] or extension
   local filename = path.filename(result_file)
-  local result = pandoc.List:new({
-    pandoc.Header(3,
-      pandoc.Link(pandoc.Str(filename), filename),
-        {filename}
-      )
-  })
+  local result = nil
 
-  if format == 'html' then
-    result:insert(result_block_html(filename))
+  if format == 'html' then 
+    result = result_block_html(filename)
   else
-    result:insert(result_block_raw(result_file, format))
+    result = result_block_raw(result_file, format)
   end
 
-  return result
-end
+  if result then
+    return pandoc.List:new{
+      pandoc.Header(3,
+      pandoc.Link(pandoc.Str(filename), filename),
+      { id = filename }
+      ),
+      result
+    }
+  end
 
+end
 
 local function code_blocks (code_file)
   local code_content = read_file(code_file)
-  local code_attr = pandoc.Attr(code_file, {'lua'})
-  return {
-    pandoc.CodeBlock(code_content, code_attr)
-  }
+  if code_content then
+    local code_attr = pandoc.Attr(code_file, {'lua'})
+    return {
+      pandoc.CodeBlock(code_content, code_attr)
+    }
+  end
 end
 
 function Pandoc (doc)
   local meta = doc.meta
   local blocks = doc.blocks
 
-  -- Set document title from README title. There should usually be just
-  -- a single level 1 heading.
-  blocks = blocks:walk{
-    Header = function (h)
-      if h.level == 1 then
-        meta.title = h.content
-        return {}
+  -- Ensure the document has a title: already set or first level 1 heading.
+  if not meta.title then
+    blocks = blocks:walk{
+      Header = function (h)
+        if h.level == 1 and not meta.title then
+          meta.title = h.content
+          return {}
+        end
       end
-    end
-  }
+    }
+  end
 
-  -- Add the sample file as an example.
-  blocks:extend{pandoc.Header(2, 'Example', pandoc.Attr('Example'))}
-  blocks:extend(sample_blocks(stringify(meta['sample-file'])))
-  blocks:extend(result_blocks(stringify(meta['result-file'])))
+  -- Add the sample file source and result as an example if both present.
+  local spl_blocks = sample_blocks(stringify(meta['sample-file']))
+  local res_blocks = result_blocks(stringify(meta['result-file']))
+  if spl_blocks and res_blocks then
+    blocks:extend{pandoc.Header(2, 'Example', pandoc.Attr('Example'))}
+    blocks:extend(spl_blocks)
+    blocks:extend(res_blocks)
+  end
 
   -- Add the filter code.
   local code_file = stringify(meta['code-file'])
-  blocks:extend{pandoc.Header(2, 'Code', pandoc.Attr('Code'))}
-  blocks:extend{pandoc.Para{pandoc.Link(pandoc.Str(code_file), code_file)}}
-  blocks:extend(code_blocks(code_file))
+  local cde_blocks = code_blocks(code_file)
+  if cde_blocks then
+    blocks:extend{pandoc.Header(2, 'Code', pandoc.Attr('Code'))}
+    blocks:extend{pandoc.Para{pandoc.Link(pandoc.Str(code_file), code_file)}}
+    blocks:extend(cde_blocks)
+  end
 
   return pandoc.Pandoc(blocks, meta)
 end

LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright © 2021–2022 Albert Krewinkel and contributors.
+Copyright © 2022–2024 Julien Dutant.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal