Adding quarto extensions?

[coatless]

👋 Hi

I'm interested in having altdocs generate a Quarto website that uses a few Quarto extensions.

After reading through the documentation on customization, I'm under the impression that any resource in altdoc will be copied entirely to _quarto before the website is rendered. So, if we place altdocs/_extensions, then any extension will be copied into _quarto for the render phase.

What I'm unsure about is whether I can write a script that modifies an intermediary generated when going from Rd to Qmd or md. Is this possible?

[etiennebacher]

What I'm unsure about is whether I can write a script that modifies an intermediary generated when going from Rd to Qmd or md. Is this possible?

Hi, I don't think it's possible for now but @vincentarelbundock is the one who added support for the Quarto website (and uses it more than me) so he might have more info. Just out of curiosity, why do you want to modify the intermediary qmd files?

[coatless]

@etiennebacher thanks for the quick reply!

I'm interested in being able to stylize and modify different parts of the Quarto document before the final rendering. To add the styling, I need to register certain markup values that can be interpreted by a Quarto extension. I'm specifically interested in being able to have a "tabbed" section between rendered output and interactive output under the Example section.

P.S. Great to know that it was @vincentarelbundock who added it and is even using it for the famed modelsummary website package! 😄

[vincentarelbundock]

Hi @coatless

What you could try is to circumvent the altdoc automatic man creation altogether:

• Loop over the files in man/
• Call altdoc:::.rd2qmd() to convert them
• Add your tabs
• Add the output to the sidebar in YAML

This is obviously more "manual", but the hard part is to convert Rd to qmd anyway, and that part is automated. The rest is relatively trivial.

[coatless]

@vincentarelbundock thanks for the quick feedback. I'll try to work on something this weekend or early next week.

If I can achieve what I set out to, would there be any desire to incorporate it as a feature into the package?

[vincentarelbundock]

Yeah, I think that might be useful. Not sure what a clean and general user interface would be. (With new features, I always try to think "could solving my one specific problem help me do other things?")

Once you know what is involved, feel free to post again and make a proposal. Ultimately it'll be @etiennebacher 's call, of course.

(Warning: I can review a PR, but I don't think either me or Etienne will have much---if any---time to write actual code.)

[coatless]

@vincentarelbundock awesome!

I should clarify: I'm not looking for any coding support; more of a home for the feature once I get it working. 😄

[etiennebacher]

Ultimately it'll be @etiennebacher 's call, of course.

The thing I want to avoid is adding code that could have side effects on other websites (I'm already spending way too much time on the docs of polars). I never use the "quarto_website" format for now so I don't have anything against adding new features for this but the changes should be limited to the quarto-related functions in altdoc (e.g .finalize_quarto_website()).

I should clarify: I'm not looking for any coding support; more of a home for the feature once I get it working.

Then hosting it in the altdoc folder in your package should be sufficient since it's never modified by altdoc::render_docs().

I'm curious to see what this will look like, feel free to add a link here when you have something working

[kylebutts]

@coatless you can use a Quarto pre-render/post-render command for this, storing your script in altdoc/.

altdoc will set up _quarto/ with all the files and then call quarto::quarto_render() on the folder. If you have a pre-render script in your quarto_website.yml, this will be triggered when rendering, so you can modify the .qmd files programatically.

[coatless]

An update of sorts a bit later than next weekend ;)

First, thanks @kylebutts for mentioning the pre-render portion. That did the trick! I wrote a quick R script that switches away from the historical R Markdown code chunks into Quarto's hashpipe style and, then, wraps the code cell with a Div that allowed for tabbifying content.

From there, I installed the extensions I needed to the altdocs/ directory. These were subsequently copied over to _quarto and still reside in docs/ once done.

To register the extensions and the pre-render, I made a few slight tweaks to the default quarto_website.yaml:

1. I added a pre-render statement under project to run the above R Script.
   • This step handled the intermediary content change/switch entirely outside of needing to modify a function in altdoc.
   • Though, I would like to submit a PR to switch generating code cells to use Quarto's hashpipe style
2. Set extension options globally for the project
   • I did assume that the first website URL corresponds to the GitHub website
3. Attached the relevant extensions.

Lastly, I needed to modified the GitHub Action worker to include a second part... But, overall, I'm really happy with the outcome!

Source: https://github.com/coatless-r-n-d/quarto-webr-in-altdoc

Live Demo: https://rd.thecoatlessprofessor.com/quarto-webr-in-altdoc/man/in_webr.html

And a screenshot in case the live demo goes down while I'm still toying around 😉

[etiennebacher]

That looks good, nice job! Is this something you would see integrated in the package? I'm thinking it might be easier to write a vignette on this so that we don't make the internals more complex.

---

Small aside: it looks like the native pipe doesn't work across lines, e.g:

mtcars |> arrange(drat)

works but not

mtcars |> 
  arrange(drat)

No clue if this is due to webr, quarto-webr or something else, I have no experience with those

[coatless]

@etiennebacher wrote a brief vignette on the repo itself. I'd like to tweak at least the line I highlighted since it shouldn't be setting things with rmarkdown style options.

---

re: are you on windows? we've had odd eol issues. or were you trying cntrl + enter instead of shift + enter?

(cntrl + enter sends only the first line; whereas shift+ enter sends the code cell.) We can save this story for another day.

[etiennebacher]

were you trying cntrl + enter instead of shift + enter?

Ah I see, doing shift + enter works indeed, thanks!