Fixed docs: load acronyms extension to preview styles

Previewing the styles was always kind of a hack between Quarto and
Pandoc. Since we directly use Quarto libraries (`log`) in our extension,
the preview was even harder.

This commit simplifies the workflow by leveraging the shortcodes: we now
load the extension by creating a symlink automatically when building the
docs (similar to what we do in tests), which allows us to use shortcodes
in articles.

Instead of using an external preview script that calls another instance
of Pandoc, the `styles` article now directly renders the desired style
with shortcodes.

However, shortcodes are now enabled on all pages of the docs; in a very
irritating manner, Quarto still parses and renders them even when they
are in code-blocks or inline code. For example, writing: "Type `{{< acr
KEY >}}` to use acronyms" will render as "Type KEY to use acronyms",
which is not what we want.

For code-blocks, we can use the `{shortcodes=false}` option, but for
inline codes we have to encapsulate them in triple braces `{{{`.

README.md

@@ -107,9 +107,9 @@ acronyms:
 
 `\acr{qmd} can be used to write technical content. \acr{qmd} use \acr{YAML}.`
 
-or the newer shortcode syntax `{{< acr KEY >}}`:
+or the newer shortcode syntax `{{{< acr KEY >}}}`:
 
-`{{< acr qmd >}} can be used to write technical content. {{< acr qmd >}} use {<< acr YAML >}}.`
+`{{{< acr qmd >}}} can be used to write technical content. {{{< acr qmd >}}} use {{{< acr YAML >}}}.`
 
 Both syntaxes render as (using default options):
 

docs/.gitignore

@@ -6,3 +6,6 @@ _site/
 
 # The `preview.png` is automatically copied from the root folder when building.
 /preview.png
+
+# The `_extensions` symlink is automatically created when building.
+/_extensions

docs/_quarto.yml

@@ -3,7 +3,9 @@ project:
   # Build the site to `docs/_site` (i.e., `_site` in this current dir).
   output-dir: "_site"
   # Automatically copy resources from parent folder (not detected by Quarto)
-  pre-render: cp ../preview.png preview.png
+  pre-render:
+    - cp ../preview.png preview.png
+    - ln -fsh ../_extensions _extensions
 
 website:
   title: "acronyms"

docs/articles/shortcodes.qmd

@@ -18,11 +18,11 @@ arguments that can be used, and gives a few example.
 
 ## The `acronym` shortcode
 
-The `{{< acronym KEY >}}` shortcode replaces an acronym in the document, where
+The `{{{< acronym KEY >}}}` shortcode replaces an acronym in the document, where
 `KEY` identifies the acronym we want to replace (exactly as `\acr{KEY}` does
 in the legacy syntax).
 
-For convenience, the shorter `{{< acr KEY >}}` can be used instead; both will
+For convenience, the shorter `{{{< acr KEY >}}}` can be used instead; both will
 invoke the same function, and thus have the same arguments and behaviour.
 
 The key is mandatory, and **acronyms** will raise an error if not provided.

docs/articles/styles.qmd

@@ -2,8 +2,15 @@
 title: "Styles"
 description: >
   List and preview of the available styles for replacing acronyms.
-# We require `knitr` to use `bash` code chunks.
-engine: knitr
+filters:
+  - acronyms
+acronyms:
+  keys:
+    - shortname: qmd
+      longname: Quarto document
+  # We only want to preview the acronyms' style, not the full document.
+  insert_loa: false
+  insert_links: false
 ---
 
 To replace acronyms in your document, **acronyms** offers several
@@ -21,6 +28,8 @@ For each of the style examples, we will use the following document
 
 ```yaml
 ---
+filters:
+  - acronyms
 acronyms:
   keys:
     - shortname: qmd
@@ -32,9 +41,9 @@ acronyms:
   insert_links: false
 ---
 
-First use: \acr{qmd}
+First use: {{{< acr qmd >}}}
 
-Next uses: \acr{qmd}
+Next uses: {{{< acr qmd >}}}
 ```
 
 
@@ -44,25 +53,25 @@ Next uses: \acr{qmd}
 
 ## long-short
 
-```{bash, long-short, echo=FALSE, results='asis'}
-../preview_style.sh "long-short"
-```
+First use: {{< acr qmd style="long-short" first_use=true >}}
+
+Next uses: {{< acr qmd style="long-short" first_use=false >}}
 
 ## short-long
 
-```{bash, short-long, echo=FALSE, results='asis'}
-../preview_style.sh "short-long"
-```
+First use: {{< acr qmd style="short-long" first_use=true >}}
+
+Next uses: {{< acr qmd style="short-long" first_use=false >}}
 
 ## long-long
 
-```{bash, long-long, echo=FALSE, results='asis'}
-../preview_style.sh "long-long"
-```
+First use: {{< acr qmd style="long-long" first_use=true >}}
+
+Next uses: {{< acr qmd style="long-long" first_use=false >}}
 
 ## short-footnote
 
-```{bash, short-footnote, echo=FALSE, results='asis'}
-../preview_style.sh "short-footnote"
-```
+First use: {{< acr qmd style="short-footnote" first_use=true >}}
+
+Next uses: {{< acr qmd style="short-footnote" first_use=false >}}