Scrivener3 + LaTeX for the LaTeX newbie

[AmberV]

@rdale

Are you saying that the MMD “heading 1” syntax (a single # sign at the beginning of a line) translates into “\chapter{my title here}” in the MMD->LaTeX->PDF compile? Being new to LaTeX,I had assumed that it didn’t necessarily have the concept of a “chapter” in its syntax (as with HTML’s H1, H2, etc…), and that the \chapter function was part of the template.

That’s a good question, I should have clarified that further. The heading cascade that MultiMarkdown uses by default goes like this:

1. part
2. chapter
3. section
4. subsection
5. subsubsection
6. paragraph

The latter is as special kind of paragraph—not a paragraph in the sense of what you’re reading right here, but something more like a paragraph with a run-in heading (it depends a bit on the style being used).

So one approach, if you don’t need parts, is to start your heading level at 2, but that’s a bit awkward in both MMD and Scrivener. You can do that with Scrivener—in the Section Layouts: Title Options tab at the bottom you’ll find a place to force a layout to use a specific number of hashes (the default being to use outline order). But then you have to make a different layout for every level of depth and manage all of that in the project Type by structure settings. That works, but it’s much nicer to just have a Layout that is called “Heading with Text” that handles everything Part I down to a titled paragraph.

So to that end, a better approach is to make use of the “Base Header Level” MMD metadata key (insert either into the project’s metadata pane, or in the Format if that is an intrinsic part of its design). That essentially offsets the effective hash level by whatever value you define as “top”. A base header level of “1” is the default, where one hash = one hash = part. Set to “2”, one hash = two hashes = chapter.

Is there somewhere that shows what the translation is from MMD syntax to standard LaTeX, so I know when MMD is sufficient vs. when I will have to inject raw LaTeX?

I’m not aware of a comprehensive resource, save to say that if MMD has syntax for it then it tries to do something effective with LaTeX in the output. So your primary clue that you may need to dip into raw LaTeX is if there is no native MMD syntax to do thing you’re trying to do. If there is a native way of doing it, then chances are it will “just work”. For example, here is a chapter heading using a custom bookmark label:

## Name of Chapter [myhook] ##

The LaTeX result of that code:

\chapter{Name of Chapter} \label{myhook}

Instead of the default:

\chapter{Name of Chapter} \label{nameofchapter}

You could then refer to this chapter in a cross reference using MMD’s native syntax for doing so: [like this][myhook]. But if you’re using the default heading behaviour both the cross-ref and the heading will be interpolated to the same internal label. Thus [Name of Chapter] becomes “Name of Chapter (\autoref{nameofchapter})”, which when typeset will come out like “Name of Chapter (Chapter 1)”. Or in the first example, “like this (Chapter 1)”. Not MMD is not only generating the autoref code, but building the parenthetical structure and visible text as well (and it is LaTeX that is responsible for knowing that “Name of Chapter” is in fact a chapter and that it is the first chapter.

Cross-reference are then super easy in Scrivener. You just drag the thing into the editor that you want to link to and put brackets around the name. You get a handy link yourself that you can use while writing, and the brackets make the link functional in the end.

So as mentioned one case to use raw LaTeX is when MMD doesn’t do a thing—but the above is a good example of the other case, where you want a different output than what is automatically generated. Maybe you don’t want the name of the document in a parenthetical, or want to use a different referencing package than what provides autoref, then you would have to build you own cross-reference via Styles in Scrivener or something.

@nontroppo

So really you do not need to “learn” LaTeX so much as be aware of the markup available with MMD/Pandoc

Very true! If you’re happy with stock output, or you have a stylesheet and preamble all supplied to you and don’t really care to make any modifications to, then chances are you won’t need to learn much at all. If you want to do something like the Scrivener user manual… yeah you might need to learn a thing or two. But even there, I was able to accomplish a good 75% of that by just searching tex.stackexchange for commonly asked questions. This is a decades old system, and I’ve found nearly everything you might need to do is answered many times over, and more often than not there is some package you can make use of that does exactly what you want and takes maybe ten minutes to figure out how to use. I would put my level of LaTeX knowledge down as “dabbler” at best. I know enough to know where to go to look for packages, where to get help when I’m stuck, and just enough to make my own simple layouts when need be. But I’m by no means an expert, which should demonstrate how far one can go with this approach with a little investment in learning.

Lastly, if you do want an approach that is closer to the source, you could try a template that looks to generate .tex on its own, without the Markdown layer. You probably will need to learn a little more if you go that route—but I’ve been taking a stab at a sort of easy-enough purist Scrivener+LaTeX compile setup, in this thread. From the sounds of it, you might have ended up with a similar template? If so—it might be intended to be used more like mine, where you are compiling to .txt instead of through any Markdown engine.