The goal was:
categorize my snippets/gh-gists and get a convenient tag- and text-search;
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:
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