Adjust heading level of included document

[lorenzoFabbri]

Description

I tend to split my documents into separate Quarto files, with the aim of reusing them later on. Suppose the main Quarto document has a section called # Data description, and that inside this section I am including another file containing the section # Numerical variables, is it possible to adjust the level of the heading in the included document so that it will render as ## Numerical variables?

[mcanouil]

You can't using the include shortcode as it basically only copy/paste the content into the main document.
Also for this to work, the shortcode would need to know at which level it is called and bump the level of any subsequent header of the included document.
You could possibly write a Lua filter that does that.

[rben01]

The shortcode could take a parameter that specifies how much to bump each heading; this is what Asciidoctor does. https://docs.asciidoctor.org/asciidoc/latest/directives/include-with-leveloffset/#manipulate-heading-levels-with-leveloffset

[cscheid]

Our includes work on situations more general than just markdown. That just won't work.

[gadenbuie]

You could (probably, I haven't tested it) do this with my quarto extension: partials.

You'd create the child document in a file like _description.qmd:

#{{ level_bump }} Data description

The data description here with all the usual Quarto features...

which you'd then include in your parent document like this:

# Numerical variables

{{< partial _description.qmd level_bump="#" >}}

Or without the level bumping like this:

{{< partial _description.qmd level_bump="" >}}

(You could also use more advanced mustache templating features to avoid needing the level_bump="".)

[rben01]

Our includes work on situations more general than just markdown. That just won't work.

But you only need to increment the heading level when including markdown (right?), so not working on other kinds of content should be fine? Maybe I'll take some time this weekend and see if I can't whip up an extension for this...

[the-solipsist]

You could use the include-files extension from pandoc-ext, which allows you to adjust the heading-levels of included files using the syntax:

# Title f

This is `file-f.md`.

## Subtitle f

```{.include} >> equivalent to {.include shift-heading-level-by=2}
file-a.md
```

```{.include shift-heading-level-by=1} >> force shift to be 1
file-a.md
```

I hope that helps.

[cscheid]

Be aware that this extension doesn't appear to support a number of quarto-specific markdown features (because it uses a plain pandoc.read() call). For example, shortcodes won't be evaluated.

[jjallaire]

Here's a Pandoc filter that does this:

-- Shift header levels within a marked container div
-- Usage: ::: {.shift-headings by=1}
--        {{< include file.md >}}
--        :::

function Div(el)
  if el.classes:includes("shift-headings") then
    local shift = tonumber(el.attributes["by"]) or 1
    return el:walk({
      Header = function(h)
        h.level = h.level + shift
        return h
      end
    })
  end
end

Usage:

::: {.shift-headings by=1}
{{< include _foo.md >}}
:::

[mcanouil]

I've added a slight variation of this to the external shortcode extension in 1.4.0 (https://github.com/mcanouil/quarto-external)

quarto add mcanouil/[email protected]

{{< external <URI> shift-heading-level-by=1 >}}
{{< external <URI>#<section-id> shift=1 >}}