Snippets gonna be organized

Yep, I’ve settled a way to organize github-gists for myself, with qmd/Quarto (“VΠ-snippets”↑ at navbar).

The goal was:

1. categorize my snippets/gh-gists and get a convenient tag- and text-search;

2. ability to annotate snippets, without making changes to the snippet itself.

While playing with Hugo, Distill and Quarto, I came to the following solution:

Implementation details

My examples in this article leverage Quarto facilities to “wrap” GitHub gists. But it seems not too difficult to implement such approach with other static site generator for files/snippets under generic VCS repo.

Article file structure

article/
    _g/
        .git
        file1
        file2
    index.qmd

Adding original gist as git-submodule under some underscored directory (_g/) within the article/post gives us:

git-subtree? – up to you.

• keeping snippet and its “sidecar” metadata separate

  annotations and examples (.md, .Rmd, .qmd) are located and versioned along with the site/blog, but not at the snippet’s origin (e.g. GitHub gist repo)

• avoiding duplicate code

  underscored directory will be ignored by distill/quarto utility, by default, so you can control which chunks of code should appear in the article, referencing them in include clause

Thus we do not commit same code again (submodule is just a link), and have all the required snippets updated and available to include and annotate.

include-code-files extension

That is a pandoc filter required to include source files checked out from GitHub gists, e.g. with such include clause in the qmd-file:

```{.py include="_gist_submod/snippet.py" startLine=6 endLine=39}
```

Filter(s) you have checked out from the pandoc repo becomes enabled with _extensions/<Filter>/_extension.yml:

title: include-code-files
contributes:
  filters:
    - ../_pandoc_lua_filters/include-code-files/include-code-files.lua

In this example Pandoc lua-filters added as git-submodule under _pandoc_lua_filters/, you see.

See also: pandoc/lua-filters, Quarto::Extensions