How to easily compile a Word document with simple markdown and rich text?

I have a simple question about the hybrid use of markdown and rich text, but the discussions I’ve read seem very complicated or, at least, I didn’t find an easy solution for what is (I think) a simple problem.
This is what I need. I used very simple markdown, basically for italics and bold. I used Scrivener styles for headings (1 for sections, 2 for subsections), and headings are in the same document sections as the body text (the body text is formatted as “no style”).
I need to compile a Word document. I use Pandoc to .docx and the Pandoc Word Document format. I assign Group and Text Sections to the “Text Section” layout, as suggested here (so far, I have only tried with a very short essay, about 5k words, so there is no significant complexity, just a couple of sections and subsections).
Then, in the settings, it seems I have two options.

  1. If I choose “Convert rich text to MultiMarkdown”, I get a document with proper paragraphs, section headings, footnotes, and so on. But all the markdown italics and bold appear as markdown, not rich text.
  2. If I deselect “Convert rich text to MultiMarkdown”, I get a document with italics and bold as rich text. Still, the whole text of each section appears piled up, including headers and paragraphs, as if they formed a single block without paragraph spacing.

Perhaps I’m missing something. Is there a straightforward workaround to produce a Word document using Pandoc from the compile menu? Thanks!

Paragraphs

As noted in this thread, if you’re going to work this way you would be doing yourself a favour by formatting paragraphs correctly in the text editor. But there is a way to fairly safely convert word processor paragraph formatting to Markdown, linked to in that post.

The potential main issue with automation like this is that it can mess up things that aren’t paragraphs, that actually do need to be adjacent lines, like verse, tables, definition lists and metadata blocks. It means you have to be much more diligent in styling everything that shouldn’t be considered a body paragraph, even if the only reason you’re using that style is to simply say “don’t change the line spacing here”.

In my opinion it’s easier, less prone to human error, and cleaner all around to form the habit of hitting Enter twice between paragraphs—or not, when you really do need something else.

And yes, that total conversion checkbox is only for those that aren’t using Markdown at all. It’s very limited in its usefulness outside of that. For example, it’s a good way for someone curious about the system to get a sense of what kind of output quality they will be getting, and if they will enjoy the post-compile formatting aspect (as opposed to learning the compiler excessively). If your already in though, and you want to use this as a writing method (to some degree), it’s best to move beyond it as soon as possible, and start using styles for effects you want that are out of the ordinary, rather than learning to use styles as a way of fighting against a machine to stop it from doing what you don’t want. One is fulfilling, the other is frustrating—at least in my humble opinion. :slight_smile:

Heading

  1. Double-click on your compile Format in the left sidebar to edit it.

  2. In the Styles pane, click the + button in the top right to add a style, and add the “Heading 1” style, from your project.

  3. In the Prefix field, type #⎵ (with the space after it).

    Heading 2 would be ##⎵, and so on.

Personally I’d consider outlining more though, than typing headings in like this. You get hierarchical headings for free with Scrivener+Markdown. You don’t have to set anything up other than choosing a section layout that generates headings. The only time you have to configure anything is if you have an outline that isn’t logical (like level 5 should really be level 3 for some reason—I do that sometimes, where I want more organisation than the reader does).

So again we are at that principle of looking for the least resistance and making that the workflow, and using configuration and tools only when you need something different. Instead of having to manually configure headings so that they work at all, they just work, and only in that rare case otherwise would you have to learn/take the effort to change how that works.

3 Likes

Thank you!

This makes sense, I didn’t know about that Markdown requirement for paragraphs.

This approach also makes things easier. In this case, I used section types to distinguish between those that will appear with a heading and those that won’t. I can rely on outlining, and I no longer need to worry about formatting headings. The result of compiling Pandoc is now correct (except that I set it to override the font with Times New Roman, but it doesn’t work).

Still, I guess I have no reason not to use Scrivener’s compile to Word with the two “Convert Markdown” and “Convert Multimarkdown” options selected, and take advantage of the already built-in formats for convenience, instead of going through Pandoc. Am I correct? Bold and italics appear as rich text, although ~~ is not transformed into a strikeout, but into a subscript.

1 Like

How exactly did you go about doing that? For me I must use a word processor to edit the default stylesheet file—or to make my own Pandoc template in other words. In case you meant trying to do something in Scrivener, I did write a brief tutorial and creating your own document designs. It’s quite simple, and I would say even easier if you use LibreOffice, and ODT, as its stylesheet system is cascading, a bit like CSS is. I.e. to change the font to TNR you usually only have to change the master root style that everything else descends from. With Word, as I understand it, there is nothing like that and you have to change the font in each style that will be used.

But either way you’re just using word processor setup to do this, and then following the instructions provided to run your own Pandoc command-line in the compile settings—a good skill to learn anyway as Pandoc has a lot of really useful command-line flags.

Still, I guess I have no reason not to use Scrivener’s compile to Word with the two “Convert Markdown” and “Convert Multimarkdown” options selected…

This post here probably best describes the pros and cons of that approach. I can’t think of a single advantage to using Scrivener’s DOCX generator over Pandoc’s, especially once you learn the above. You’ll have way more design freedom since you’ll have everything Word or LibreOffice can do, rather than the small subset the compiler offers.

3 Likes

I have just learnt to do this, and indeed it easily gives me all the flexibility I need. Thanks!

Another issue encountered: The paragraph formatted in Scrivener as a Block Quote doesn’t appear as such in the compiled document, but is collapsed into the previous paragraph, with the ‘>’ character preceding it. I’ve made sure to click Enter twice. I’m not sure where the problem lies.

1 Like

Looks like you’re making good progress! Using Scrivener+Pandoc is definitely the way to go, and I’m happy to help you achieve what you’re looking for—I have lots of practice, as this is how I wrote my book whose publisher required a docx file.

To troubleshoot your blockquoting issue, my recommendation is to see if this happens also when you are just using Pandoc alone (no involvement with Scrivener) to convert a simple md file to docx on the command line. If that has the desired output, next try doing the same thing but adding in your reference to your reference docx in your command. Still fine? Then I guess it’s something to do with your Scrivener set up and we can go from there.

Once you get block quotes working properly in your Scrivener-to-docx setup, next ask yourself if you’ll ever need to have the line that follows a blockquote to be unindented—for example, where the line afterwards is meant to be a continuation of the paragraph that preceded the blockquote. If yes, then you should consider incorporating the complex-paragraphs lua filter described and linked to here.

If you end up not being able to solve your first block quote problem, let me know. I could probably share my personal Scrivener template and you could see if that works for you. As the post I link to above notes, this template is set up to control post-blockquote indenting in my own special way (although no reason the template couldn’t also be used with the complex-paragraphs filter as well).

3 Likes

I have opted to write the angle bracket before the quote and change it to No Style. I already use the markdown angle bracket sign for quotes in my note-taking app, so I guess this is the simplest solution for me, until the bug is solved. But I will let you know if I encounter any other issues. Thanks!

I have encountered a new issue when compiling my document into Word with Pandoc. I want the compiled document to include some comments for the editors. Pandoc renders them this way: “{==body text==}{>>comment<<}”, and this is how Word displays them, not as Word comments. Is there a workaround?

That would be coming from Scrivener. These are CriticMarkup style markings, that vanilla Pandoc does not process without pre-processing (or maybe a custom filter). Secondarily, it sounds like you may have gone with the “Basic Pandoc” compile format as a starting point, rather than the “Pandoc Word Document” format. That’s no big deal, you can copy and paste settings from one to the other easily enough. If you take a look at the latter, in the Annotations compile format pane, you’ll see the code that Pandoc looks for to render Word-style comments. Copy that string, and paste it back into your working format in the same place.

That would be easier than going down the CriticMarkup rabbit-hole, particularly on Windows, as the tools I’ve found for integrating it with Pandoc are Python based, or otherwise just more UNIX-friendly. If all you need is comments anyway, the above is sufficient. The other features are more for version tracking.

3 Likes

Using “Pandoc Word Document” solves the issue, thanks!