Best workflow for extension documentation website that uses extension?

[jimjam-slam]

Description

I'm wondering if folks (either the Quarto team or the community have opinions) on the best way to maintain a documentation website for an extension.

For Sverto, I have a /docs directory that contains the website, and I publish that to GitHub Pages using quarto publish (which iirc puts it on the gh-pages branch).

Since this website uses the sverto extension itself, it needs a copy of the extension inside the website directory. At the moment I just make a copy straight from the project root, but that pollutes the git repo with a lot of double handling and leads to a lot of mistakes and confusion.

One solution could be to publish the website using GitHub Actions and add a step to install the extension before render. The downside is that if you looked at the website source, it wouldn't be obvious that the extension was used, but it would solve the double-handling. A symlink feels like dangerous overengineering.

Do folks have an opinion on best practice here?

[coatless]

@jimjam-slam I'm using a symlink to connect _extensions/ into the docs directory. Though, this requires a custom publish step to remove the symlink before publishing it onto the gh-pages branch as symlinks don't play nicely in tars.

https://github.com/coatless/quarto-webr/blob/5ed080286be2fb25e7f08e106e8cb9a7594cb58a/docs/_extensions

https://github.com/coatless/quarto-webr/blob/5ed080286be2fb25e7f08e106e8cb9a7594cb58a/.github/workflows/publish-demo.yml#L102-L105

If you have more than one extension, you likely want the physical _extensions folder and, then, include a link directly to the extension folders.

[jimjam-slam]

Thanks @coatless, this is super helpful! Maybe a symlink is the way to go after all 🤔

[jimjam-slam]

@coatless Did you have a problem running quarto render when your extension directory is a symlink?

In jimjam-slam/sverto@dev, I've set up docs/_extensions/sverto to symlink to _extenions/sverto. But when I do, the extension project type isn't recognised:

ERROR: Unsupported project type sverto

Stack trace:
    at projectType (file:///Users/rensa/Applications/quarto/bin/quarto.js:37943:15)
    at projectContext (file:///Users/rensa/Applications/quarto/bin/quarto.js:72786:30)
    at eventLoopTick (ext:core/01_core.js:183:11)
    at async render (file:///Users/rensa/Applications/quarto/bin/quarto.js:81779:19)
    at async Command.fn (file:///Users/rensa/Applications/quarto/bin/quarto.js:81954:32)
    at async Command.execute (file:///Users/rensa/Applications/quarto/bin/quarto.js:8104:13)
    at async quarto (file:///Users/rensa/Applications/quarto/bin/quarto.js:114999:5)
    at async file:///Users/rensa/Applications/quarto/bin/quarto.js:115017:9

If I remove the symlink and copy the files over manually, it renders fine (well, at least this error doesn't stop it at the beginning 😜). Have you seen anything like this? I'm not punishing remotely yet, this is all just happening locally.

[jimjam-slam]

Interestingly, I'm able to render quarto-webr's /docs site just fine! Maybe this is limited to custom project types? Seems weird that a symlink would behave one way for one type of extension and another for another type!

EDIT: made a reprex that works fine! Must be something specific to my project setup 😅

Nope, I had the project name wrong. The reprex does indeed reproduce this behaviour for me! I've filed an issue for this.

[jimjam-slam]

Apparently symlinks are not supported at all (and are actively screened out)!