Markdown heading level


I’m in the process of bringing my thesis (which up until now I’d been writing in a text editor as LaTeX) into Scrivener. For the moment, I’m using Markdown export, as it lets me easily compile a Word document via pandoc. (Pandoc’s compile is nice and quick, whereas a full LaTeX build of the thesis document to e.g. check citations is rather time-consuming. Also, the Word document is easier for others to review and do comments/proposed changes.)

My draft structure produces sub-optimal output. I have three ‘Parts’ to my draft, and as a consequence, the actual chapters are second-level documents. Thus, they end up with what I intended as the Chapter headings like this:

## Chapter Title ##

I would like them to be top-level, like so:

# Chapter Title #

Is there a setting to adjust the structure-based levels? Or should I move away from my part-based Draft structure?

What purpose are the parts serving in the output, if they are not meant to be technically at “level 1” of the document structure? Are they purely for internal organisation and deselected from being included in compile?

If so there isn’t a super simple switch in Scrivener for doing that, given how the compiler takes what is the least indented level in the compile Contents pane and assigns that to h1, even if there is actually nothing on that level that outputs.

No fear though, there are two different alternatives you can take to get this done, but I would recommend making this adjust with Pandoc settings itself first.

To test the theory, compile an .md file and add this to your Pandoc command line: --shift-header-level-by=-1 which, as you might guess, subtracts one from each found header level in the document. h2 because h1, h3 becomes h2 and so forth.

If you use Scrivener to compile to DOCX directly, and would like to keep doing so rather than having to switch to command-line work in post, then you can customise the command-line switches Scrivener uses to generate output:

  1. Double-click on the compile format you are using in the left sidebar (like “Pandoc Word Document”) to edit it.

  2. At the top of the sidebar, click the gear button and add regular “MMD” to the list of supported file types for this Format, if necessary, then use the dropdown to the left to pick “MMD”.

    You should see a Processing pane appear, go there.

  3. Enable the Post-process on command-line option, and fill in the fields with the following values:

    • Switch the Script button to Path, with:

    • Arguments:

      --to=docx --shift-heading-level-by=-1 --output=<$outputname>.docx
    • Finally tick both of the settings to delete temporary source files and images.

Save your new format, maybe renaming it to something clear so you know it’s going to shift headings, and now you’ve got everything set up so you get the same result you are accustomed to. When you compile you’ll get a .docx file and nothing more, only chapters will now be h1.

If you’d rather solve this in Scrivener itself—maybe you also want to use MultiMarkdown for LaTeX—then there is another approach that can essentially shift headings in Scrivener. But it’s a little more involved and will reduce your outlining flexibility going forward. So I’ll wait to hear from you’d prefer that approach. If you’re good at figuring stuff out though, pay head to the Section Layout setting, under the Title Options tab, that lets you manually set the hash level for a Layout. You’d then have to go about using Scrivener more like a standard user, creating Section Types for each level of heading you intend to use, and creating Layouts for each one of them, each set to the correct number of hashes.

Ah, that’s perfect and I’d forgotten that Pandoc option. That will certainly work well for now. And yes, it’s just a way of me organising things visually, although I have just realised that there’s another way to do it - move those bits into a Front matter folder outside the Draft, and use the Compile settings Front matter option (likewise for end matter). Which means I don’t even need to alter the structure :slight_smile:

I think I can see what you mean regarding the more complex header levels - I assume then, instead of using the nesting structure in Scrivener, I’d have to set each Document to the correct section type manually? Which is where the loss of flexibility comes in?

Great, glad the simple approach works for you.

Oh no, if you go into Project Settings and check out the Section Types pane, you’ll see you can set up mapping between hierarchy depth and types, which means you can create Part, Chapter, Section, Subsection and so on types, and then make it so your outline hierarchy is automatically assigned to them.

You would then have to create a different layout for each type that has the correct number of hashes for the level you want.

It’s basically what all RTF users have to do all the time, they don’t have a simple hierarchical approach and have to map level 1 to a layout that generates a heading that looks like a part page, and level 2 to a layout that looks like a chapter break, and so on. (And that’s why we have a bunch of different project templates that have all of that wiring set up, and why there is a difference between a novel template and a novel with parts template…)

And therein lies the reduction in flexibility, it’s not major, like I say it’s how most Scrivener users work, but it’s a shift from just being able to let the outline hierarchy drive Markdown heading depth with one single easy to use layout.

Oh that’s even better.

I’m still unsure if I can make things work well with Pandoc intermediating. I like the option of generating other formats easily but it does add a little bit of complexity.

If I do need to switch to compiling straight to LaTeX from Scrivener, I assume that this mapping of the hierarchy is what I’d need to do?

Yeah, unless you chose to use Pandoc for LaTeX generation instead of MultiMarkdown. I would go for the former approach if I were you, the only reason to stick with MMD is if you already have a lot of preamble built around how MMD generates LaTeX.

Sorry yep I’m using Pandoc –> LaTeX at the moment (in addition to Pandoc –> .docx). It’s great, as long as I don’t try to do anything too complicated. And I do have a bit of complexity because I’m using different languages, including RTL and complex scripts.

Hmm, I was thinking I might be wrong about having to use the Processing pane. Scrivener does allow you to adjust the heading shift for Pandoc, it’s a setting in the Metadata compile pane at the very bottom. But unfortunately it doesn’t look like it accepts a value of ‘-1’. You can only shift up. That’s probably something we can fix, as we weren’t aware of that being valid when it was implemented.

But at least you have something that works for now. :slight_smile:

Yes all good for this stage of things. I’ll undoubtedly be back with more questions over time.