soupault

This widgets allows to generate a so-called “revisions table” of the filename contained in a DOM element of id history, based on its history. Paths should be relative to the directory from which you start the build process (typically, the root of your repository). The revisions table notably provides hyperlinks to a git webview for each commit.

For instance, considering the following HTML snippet

<div id="history">
  site/posts/FooBar.org
</div>

This plugin will replace the content of this <div> with the revisions table of site/posts/FooBar.org.

The base of the URL webview for the document you are currently reading is https://src.soap.coffee/soap.coffee/lthms.git.

The template used to generate the revision table is the following.

<details id="history">
  <summary>Revisions</summary>
  <p>
    This revisions table has been automatically generated
    from <a href="https://src.soap.coffee/soap.coffee/lthms.git">the
    <code>git</code> history of this website repository</a>, and the
    change descriptions may not always be as useful as they should.
  </p>

  <p>
    You can consult the source of this file in its current version
    <a href="https://src.soap.coffee/soap.coffee/lthms.git/tree/{{file}}">here</a>.
  </p>

  <table class="fullwidth">
  {{#history}}
  <tr>
    <td class="date"
{{#created}}
        id="created-at"
{{/created}}
{{#modified}}
        id="modified-at"
{{/modified}}
        >{{date}}</td>
    <td class="subject">{{subject}}</td>
    <td class="commit">
      <a href="https://src.soap.coffee/soap.coffee/lthms.git/commit/{{filename}}/?id={{hash}}">{{abbr_hash}}</a>
    </td>
  </tr>
  {{/history}}
  </table>
</details>

We use the built-in preprocess_element to implement, which means we need a script which gets its input from the standard input, and echoes its output to the standard input.

[widgets.generate-history]
widget = "preprocess_element"
selector = "#history"
command = 'scripts/history.sh templates/history.html'
action = "replace_element"

This plugin proceeds as follows:

1. Using an ad-hoc script, it generates a JSON containing for each revision
   • The subject, date, hash, and abbreviated hash of the related commit
   • The name of the file at the time of this commit
2. This JSON is passed to a mustache engine (haskell-mustache) with a proper template
3. The content of the selected DOM element is replaced with the output of haskell-mustache

This translates in Bash like this.

function main () {
  local file="${1}"
  local template="${2}"

  tmp_file=$(mktemp)
  generate_json ${file} > ${tmp_file}
  haskell-mustache ${template} ${tmp_file}
  rm ${tmp_file}
}

Generating the expected JSON is therefore as simple as:

• Fetching the logs
• Reading 8 line from the logs, parse the filename from the 6th line
• Outputing the JSON

We will use git to get the information we need. By default, git subcommands use a pager when its output is likely to be long. This typically includes git-log. To disable this behavior, git exposes the --no-pager command. Besides, we also need --follow and --stat to deal with file renaming. Without this option, git-log stops when the file first appears in the repository, even if this “creation” is actually a renaming. Therefore, the git command line we use to collect our history is

function gitlog () {
  local file="${1}"
  git --no-pager log \
      --follow \
      --stat=10000 \
      --pretty=format:'%s%n%h%n%H%n%cs%n' \
      "${file}"
}

This function will generate a sequence of 8 lines containing all the relevant information we are looking for, for each commit, namely:

• Subject
• Abbreviated hash
• Full hash
• Date
• Empty line
• Change summary
• Shortlog
• Empty line

For instance, the gitlog function will output the following lines for the last commit of this very file:

Website reorg
05617fa
05617fad8255248ee8ac8796e40a99529e1c8e8c
2022-10-23

 site/{ => posts}/cleopatra/soupault.org | 3 +++
 1 file changed, 3 insertions(+)

Among other things, the 6th line contains the filename. We need to extract it, and we do that with sed. In case of file renaming, we need to parse something of the form both/to/{old => new}.

function parse_filename () {
  local line="${1}"
  local shrink='s/ *\(.*\) \+|.*/\1/'
  local unfold='s/\(.*\){\(.*\) => \(.*\)}/\1\3/'

  echo ${line} | sed -e "${shrink}" | sed -e "${unfold}"
}

The next step is to process the logs to generate the expected JSON. We have to deal with the fact that JSON does not allow the last item of an array to be concluded by ",". Besides, we also want to indicate which commit is responsible for the creation of the file. To do that, we use two variables: idx and last_entry. When idx is equal to 0, we know it is the latest commit. When idx is equal to last_entry, we know we are looking at the oldest commit for that file.

function generate_json () {
  local input="${1}"
  local logs="$(gitlog ${input})"

  if [ ! $? -eq 0 ]; then
      exit 1
  fi

  let "idx=0"
  let "last_entry=$(echo "${logs}" | wc -l) / 8"

  local subject=""
  local abbr_hash=""
  local hash=""
  local date=""
  local file=""
  local created="true"
  local modified="false"

  echo -n "{"
  echo -n "\"file\": \"${input}\""
  echo -n ",\"history\": ["

  while read -r subject; do
    read -r abbr_hash
    read -r hash
    read -r date
    read -r # empty line
    read -r file
    read -r # short log
    read -r # empty line

    if [ ${idx} -ne 0 ]; then
      echo -n ","
    fi

    if [ ${idx} -eq ${last_entry} ]; then
      created="true"
      modified="false"
    else
      created="false"
      modified="true"
    fi

    output_json_entry "${subject}" \
                      "${abbr_hash}" \
                      "${hash}" \
                      "${date}" \
                      "$(parse_filename "${file}")" \
                      "${created}" \
                      "${modified}"

    let idx++
  done < <(echo "${logs}")

  echo -n "]}"
}

Generating the JSON object for a given commit is as simple as

function output_json_entry () {
  local subject="${1}"
  local abbr_hash="${2}"
  local hash="${3}"
  local date="${4}"
  local file="${5}"
  local created="${6}"
  local last_entry="${7}"

  echo -n "{\"subject\": \"${subject}\""
  echo -n ",\"created\":${created}"
  echo -n ",\"modified\":${modified}"
  echo -n ",\"abbr_hash\":\"${abbr_hash}\""
  echo -n ",\"hash\":\"${hash}\""
  echo -n ",\"date\":\"${date}\""
  echo -n ",\"filename\":\"${file}\""
  echo -n "}"
}

And we are done! We can safely call the main function to generate our revisions table.

main "$(cat)" "${1}"

Inline equations written in the DOM under the class and using the $\LaTeX$ syntax can be rendered once and for all by soupault. User For instance, <span class="imath">\LaTeX</span> is rendered $\LaTeX$ as expected.

Using this widgets requires being able to inject raw HTML in input files.

var katex = require("katex");
var fs = require("fs");
var input = fs.readFileSync(0);
var displayMode = process.env.DISPLAY != undefined;

var html = katex.renderToString(String.raw`${input}`, {
    throwOnError : false,
    displayModed : displayMode
});

console.log(html)

We reuse once again the preprocess_element widget. The selector is .imath (i stands for inline in this context), and we replace the previous content with the result of our script.

[widgets.inline-math]
widget = "preprocess_element"
selector = ".imath"
command = "node scripts/render-equations.js"
action = "replace_content"

[widgets.display-math]
widget = "preprocess_element"
selector = ".dmath"
command = "DISPLAY=1 node scripts/render-equations.js"
action = "replace_content"