A Quarto Question (or Six)
I am converting the notes for “Managing Research Software Projects” from McCole to Quarto. Most of the changes have gone smoothly, but I’m stuck on a few things and would appreciate guidance. For reference, the materials are in this repository and you can view the rendered version here.
-
The landing page shows the contents of
index.qmd(which is good) but that page shows up as entry #1 in the table of contents (which is bad). I have tried using a# Titleheading inindex.qmdinstead of atitlefield in the YAML frontmatter, and/or adding.unnumbered,.toc-ignore, and other classes to that H1 heading, but those don’t achieve what I want.
The closest I can get to what I want is to give./index.qmdan H1 titleOverviewand add{.unnumbered}to it. It’s clumsy, in that it still creates an entry in the table of contents, but it’ll do for now. -
Each page that has bibliographic citations lists references at the bottom of that page (see for example the Project Health page). I don’t want this: I want all citations to link to the appropriate entry in the bibliography page (e.g., this page in the example project).
Addlink-citations: trueunderformat > htmlin_quarto.yml, then put:::{#refs}\n:::inbibliography/index.qmd. -
Each chapter in the tutorial is in a subdirectory of the root, e.g.,
./intro/index.qmdis rendered as./docs/intro/index.html. I want to have a slide deck alongside each chapter so that (for example)./intro/slides.qmdwould generate./docs/intro/slides.html. (Each subdirectory is going to contain images, code fragments, and other artefacts that will be included in both theindex.qmdprose and theslides.qmdslides. I find it easier to manage these if the two Markdown files are siblings.) I’ve tried setting this up a couple of different ways, but nothing has worked. What do I add to the frontmatter ofslides.qmdto tell Quarto “these are slides”, where do I put a custom template for those slides, and what do I add to the_quarto.ymlfile to create a “Slides” section in the table of contents with links to these files? Or am I going about this in completely the wrong way?
After a lot of frustration I have concluded that issue 1433 is still accurate: there’s no simple way to do what I want. I’m therefore generating slides by callingpandocdirectly. This means the styling isn’t consistent with the main pages, but it’ll do for now. -
When Quarto renders the tutorial, it create a 1.1Mbyte directory called
./docs/site_libswith various supporting files (JavaScript, CSS, fonts, etc.). Can I configure Quarto to (a) stop it from creating this directory and (b) have HTML files refer to some absolute URL to find those files instead? I want to do this because I’m going to put the generated files here in the Third Bit site, and want to share one copy of the supporting files rather than have one per workshop. (I’m likely to have seven or eight workshops served from Third Bit once I’m done converting, and 8Mbyte of redundant files makes me squeamish.)
There doesn’t appear to be a way to configure Quarto to putsite_libswhere I want it, so I’ve written a little Lua script to replace all references to it in the generated HTML with references to../quarto/site_libs(with as many..’s as needed to reach the root of the documents directory). It’s a hack, but it’ll work for now. -
I don’t like the way Quarto’s default CSS lays out description lists; for accessibility reasons I’d like notes to be rendered at the same size as main text, and there are probably several other small changes to layout that I’m going to want as well. What’s the best way to manage custom CSS given that I’m going to generate HTML separately for several different projects, but then serve them all from one site as siblings as described above? (I’m less worried about duplication here because the custom CSS will only be a few kilobytes, so this is much less urgent than the
site_libsissue.)
Putcss: assets/mccole.cssunderformat>htmlin_quarto.yml, then createassets/mccole.cssand start overriding things there. I’m also modifying links to theassetsdirectory to be../quarto/assetswhen I deploy for the reasons discussed in the previous point. -
Finally, the glossary for the workshop is in
./glossary/index.qmd, and I use a little bit of custom Lua in./bin/g.luato handle the rendering. I’d like to store the glossary in Glosario format instead, and generate HTML from that. I think I know how to do this, but if anyone has already built what I’m after, I’d be grateful for a pointer.
If you have solutions to any of these problems, please give me a shout; thanks in advance for your help.