quartodoc interlinks should validate the version of the interlinks filter being used

[machow]

Currently, the quartodoc interlinks command doesn't check anything about the interlinks quarto filter installed. However, features like quartodoc interlinks --fast cannot run on old extension versions.

We should do two things:

• validate the filter version (e.g. that it will work correctly)
• orchestrate the installation of the filter

It's okay for now if we orchestrate by telling the user what to do. But let's investigate what managing / installing quarto extensions via the quartodoc CLI commands etc.. might look like.

More on validating

There are some weird aspects of how extensions get put in _extensions that'll need to be researched. For example, from the quartodoc/docs folder, these do different things:

• quarto add ..: creates _extensions/interlinks
• quarto add machow/quartodoc: creates _extensions/machow/interlinks

[machow]

@cscheid, any idea how a program might check for a filter in the _extensions folder?

If the interlinks filter has this _extension.yml:

title: Interlinks
author: Michael Chow
version: 1.1.0
quarto-required: ">=1.2.0"
contributes:
  filters:
    - interlinks.lua

And it's path is...

_extensions/machow/interlinks/_extension.yml

What is used to determine the name? Is it just the final folder name (the "interlinks" in "machow/interlinks")?

[has2k1]

A better solution is to ship the first class lua filters (e.g. the interlinks filter) with quartodoc and have quartodoc build install (copies) the filters to the _extension directory.

This fully resolves the conflict(s) and would allow us to use lua filters in quartodoc without the reservation that they need to be installed and managed by the user.

Then only 3rd-party filters would be managed on the CLI by the user. quartodoc would also check them for compatibility.

[machow]

Shipping with quartodoc seems like a great way to orchestrate installing the filters! One weird hitch is that I'm not sure how we could include it in the quartodoc package? Basically, quarto requires the extension to live in a top-level _extensions folder. So we'd have to symlink it, or copy it in before building the package or something? Any ideas?

[has2k1]

Basically, quarto requires the extension to live in a top-level _extensions folder. So we'd have to symlink it, or copy it in before building the package or something? Any ideas?

Yes we would copy them to project/docs/_extensions. symlinking can have weird edge-cases!

We can claim the quartodoc namespace for all of quartodoc's filters. e.g.

project/docs/_extensions/quartodoc/interlinks/...
project/docs/_extensions/quartodoc/another-filter/...
project/docs/_extensions/quartodoc/and-another-filter/...
...

So quartodoc build would do the equivalent of

rm -rf project/docs/_extensions/quartodoc
cp -R /path/to/quartodoc/_extensions/quartodoc project/docs/_extensions/quartodoc

[machow]

Sorry, I meant for my question to be--any ideas how we would get the filter into the python package? It has to live at _extensions in the root for people to be able to quarto add machow/quartodoc.

So it seems like some options are...

• find some way to keep _extensions at the root of this repo, and also get it in the python package
  • e.g. could just copy it in before building? :/
• move it to be in the quartodoc directory, and disallow installing via quarto add machow/quartodoc