How to write filter than transforms title _before_ Quarto does

[itamarst]

Description

I'm working on a book. I want to manipulate the title of chapters.

Here's my code:

function Meta(meta)
  if meta.essential == true then
    meta.title = '⮞ ' .. pandoc.utils.stringify(meta.title) .. ' ⮜'
  end
  if meta.essential == false then
    meta.title = '⋯ ' .. pandoc.utils.stringify(meta.title) .. ' ⋯'
  end
  -- If essential is not set, don't do anything
  return meta
end

This works, kinda sorta. E.g. title from:

---
title: "This is chapter two"
essential: true
---

will be "⮞ 2 This is chapter two ⮜".

However:

1. The HTML table of contents (at least as generated by quarto preview) doesn't reflect the change.
2. The title I am manipulating is after Quarto has added chapter numbers. I want to manipulate it before that. I want the title to end up being "2 ⮞ This is chapter two ⮜".

Essentially I want to be able to manipulate the original title field in the YAML, before other things are done with it (passed to ToC generator, chapter number added).

Is there a way to do this?

[mcanouil]

You can't.
That's one of the few YAML metadata Quarto uses to layout the structure.

Note that if your book is HTML, you can use CSS to add this to your title.

[itamarst]

I guess maybe a pre-render script needs to modify the input files in place, rather than writing to the output directory? In which case I'm just going to give up.

[cderv]

I wrote a pre-render script, and it generates the QMD into the _book/ directory as provided by os.environ["QUARTO_PROJECT_OUTPUT_DIR"], but none of those changes show up in the corresponding HTML file.

_book is the output directory where Quarto will write the output file. This is not expected to have source document, and this folder will be removed and recreated on new render.

So you shouldn't expect something into this folder to be taken into account as part of the Quarto project inputs. Did you get this idea from some of our doc or live example somewhere ?

I guess maybe a pre-render script needs to modify the input files in place, rather than writing to the output directory?

pre-render can do things before the project starts rendering. For example, download some updates for required resources. It can also tweak some source, or even the Quarto project conflict that will be reloaded before rendering (for example, to automatically undraft some blog post in a website based on date condition)

So, depending on your use case, it can be helpful or not.

[itamarst]

I thought "output dir" meant "where should I output modified files" because overwriting existing files seemed wrong and extremely limiting in terms of use cases, and why else would the output directory be provided? I gave up on this route too and I'm just doing things manually.

[mcanouil]

output-dir is useful to change the location of the "rendered files" (a.k.a., output of Quarto CLI) in various context, for instance you might want to publish your documents using the special docs directory at the root of a branch for GitHub Pages but don't want to have to write a script to copy/move files.

[mcanouil]

From my original suggestion if you don't want to change your input files, then change the display using CSS, LaTeX, etc.

Here is a very quick & dirty example of this:¹

---
format:
  html:
    include-in-header:
      - text: |
          <style>
          h1::before {
            content: "♠ ";
          }
          h1::after {
            content: " ♠";
          }
          h2::before {
            content: "♥ ";
          }
          h2::after {
            content: " ♥";
          }
          </style>
  pdf:
    include-in-header:
      - text: |
          \renewcommand{\section}[1]{\par\vspace{1em}\noindent{\Large\bfseries $\spadesuit$ #1 $\spadesuit$}\par\vspace{0.5em}}
          \renewcommand{\subsection}[1]{\par\vspace{0.8em}\noindent{\large\bfseries $\heartsuit$ #1 $\heartsuit$}\par\vspace{0.3em}}    
---

# Header

{{< lipsum 1 >}}

## Code Block

```lua
-- This is a Lua code block
local function main()
  print("Hello, World!")
end
main()
```

### An header left alone

{{< lipsum 1 >}}

# New Level One Header

{{< lipsum 1 >}}

Footnotes

1. as I can't see your symbols on macOS, I picked more classic ones. ↩