A Quarto Question (or Six)

Posted

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.

  1. 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 # Title heading in index.qmd instead of a title field 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.qmd an H1 title Overview and 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.

  2. 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).
    Add link-citations: true under format > html in _quarto.yml, then put :::{#refs}\n::: in bibliography/index.qmd.

  3. Each chapter in the tutorial is in a subdirectory of the root, e.g., ./intro/index.qmd is rendered as ./docs/intro/index.html. I want to have a slide deck alongside each chapter so that (for example) ./intro/slides.qmd would generate ./docs/intro/slides.html. (Each subdirectory is going to contain images, code fragments, and other artefacts that will be included in both the index.qmd prose and the slides.qmd slides. 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 of slides.qmd to tell Quarto “these are slides”, where do I put a custom template for those slides, and what do I add to the _quarto.yml file 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 calling pandoc directly. This means the styling isn’t consistent with the main pages, but it’ll do for now.

  4. When Quarto renders the tutorial, it create a 1.1Mbyte directory called ./docs/site_libs with 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 put site_libs where 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.

  5. 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_libs issue.)
    Put css: assets/mccole.css under format>html in _quarto.yml, then create assets/mccole.css and start overriding things there. I’m also modifying links to the assets directory to be ../quarto/assets when I deploy for the reasons discussed in the previous point.

  6. Finally, the glossary for the workshop is in ./glossary/index.qmd, and I use a little bit of custom Lua in ./bin/g.lua to 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.

Categories: education