Basic use of Markdown as primary writing format in Scrivener

Hi,
This is a simple question about using markdown as the primary means of writing and then compiling into whatever output you want afterwards. I’ve come to really appreciate this in Ulysses.

I knew this was not Scrivener’s point of difference, but now I see Multimarkdown in the compile menu and lots of threads here about using markdown, but they are clearly not what I’m asking for and seem quite technical.

Is there a way to just write using markdown in Scrivener and worry about the formatting later?

Would be great if this was included in an FAQ somewhere. Thanks for your help.

Thanks

Hi Panthony,

I’ve never used markdown, so can’t help you directly.

There’s an entire chapter 21 Using Markdown in the manual (Help > Scrivener Manual). I’m mentioning this in case you weren’t aware of it.

You might want to have a look while you’re waiting for someone more knowledgeable to reply. :nerd_face: Hopefully it’s helpful to you.

Best,
Jim

Very nice of you to reply Jim. and no, I wasn’t aware of it, but I just took a quick look and it’s seems there are many concepts I’m unclear on so it seems overly complicated. In ulysses it was very easy to write in markdown and it would then output in whatever format you wanted, html, Wordpress post, pdf, word doc etc, and you could choose whatever style you wish or create your own. This chapter seems focussed on actually generating markdown documents and that is of unknown value to me at the moment. I wish I could find a video tutorial that explains how I could use Scrivener to just focus on the writing and leave the formatting for later. Thanks.

Just write. Use Markdown markup as needed. This is the “Purist” approach discussed in the chapter Jim referenced.

I would say that the main difference between Scrivener and Ulysses is that the former works more closely with existing Markdown conversion tools (MultiMarkdown which is embedded, and Pandoc which you can optionally install and have integrated) while the latter has its own conversion built-in. I would say that in a way, Scrivener is a “pure” Markdown tool in that it doesn’t have its own markup system that is incompatible with everything else, and if you do want to use these established systems for conversion, it is better for doing so because of that. While you can export Markdown from Ulysses, I’ve heard it’s not the best for that.

So with that in mind, with Scrivener there is ultimately more flexibility because you are working with mature and very in-depth document production capabilities provided by these tools, rather than something we put together ourselves that only allows for a few formats.

Here’s the thing though, you absolutely can just use it very simply. Try it like this: create a new blank project, and paste some Markdown you’ve written into the starter file. Go into Compile, select the MMD → HTML output at the top, and click the compile button. You don’t even have to tweak settings, because at this level of basic usage, all of the formatting is in your Markdown text. And that’s it—and that’s probably why you won’t find many tutorials or discussion threads about using Scrivener that way, because it’s that easy. Want a word processing document? Choose MMD → ODT instead, or install Pandoc and use Pandoc → DOCX (and once you do that, you’ll see ePub as well).

The reason why you see complexity, and technical threads on the forum, is because of what you can do, beyond that. You certainly do not have to, and you can only learn what you want to learn to get something done—you don’t have to ever go all-in. Here’s simple example of what I mean: instead of pasting your Markdown into the one starter file, this time, use the File ▸ Import ▸ Import and Split command, and make sure it is set to split your document by Markdown headers (of course, use a longer document for this test that has headers).

All right, now you’re getting into what Scrivener excels at, and that is composing a long document as an outline instead of into longer files with their own heading structure (more like how you have to work in Ulysses, and most other Markdown-based tools for that matter). With this mode of usage, you aren’t typing ## Heading into the editor, Scrivener is going to be doing that for you based on the structure of your outline. You can move sections around, increase or decrease their indent levels, and all of those headings will adjust automatically for you. When you compile, you’ll need to do a little more setup this time around. Click on the “Basic MultiMarkdown” format on the left, and then Assign Section Types below the preview area. A simple approach is just assign all types to the “Text Section with Heading” layout. This will do what I just described, each level of indent in the outliner becomes a ## Heading with the hash depth worked out for you, followed by whatever text content is in that outline item of the binder.

If you used the same document for both tests, the result should be identical in output. The only difference is in how you work with that text in the writing interface.

So that’s where I would start, and maybe if that’s all you need, that’s where the learning process could end as well. As with most things in Scrivener, you only need to learn something if you want to get more out of the software. Markdown and rich text users alike both have extremely basic ways of using the software that require minimal learning. Thing is, most people eventually do want more, so that is what you see in the documentation and elsewhere. Scrivener scales up to very complex workflows, but that gives you the ability to do crazy things. It would take an awful lot of work to make a simpler tool produce something like our user manual PDF (which is yes, Markdown), and in some tools you just couldn’t do it at all without bringing other tools into the mix.

8 Likes

Wow. Amber. Thanks so much for taking the time to respond in such depth. I now have a much better understanding of how markdown in this case MMD can work. My confusions stemmed (partly) from my unfamiliarity with file extensions .tex, .odt, .fodt. I was looking for a markdown to .docx, .pdf and .rtf and didn’t see any.

It seems I will have to learn Pandoc to make such conversions and I’ll have to assess whether that is worth the time for me.

I also have no need to import large markdown documents at this time.

Fundamentally, if I write using MMD, it seems that to get all of the conversion possibilities Scrivener has native to using it’s rich text formatting, I will have to use Pandoc. Pandoc would not be necessary for .odt, .fodt, and .tex files. Do I have that right?

Thanks again for your time.

before you go too far learning Pandora, do as Amber suggests. Try it. I use that feature a lot and all I ever did was pick the Pandoc option that produces a DOCX (Word) file.

keep it simple enough till you need complexity.

2 Likes

My confusions stemmed (partly) from my unfamiliarity with file extensions .tex, .odt, .fodt. I was looking for a markdown to .docx, .pdf and .rtf and didn’t see any.

That originates in part from what MultiMarkdown itself is capable of. We’d love to include Pandoc in the software, but at 130mb, you can understand why we don’t. :slight_smile: MMD on the other hand clocks in at a tidy 1.6mb. We have icon graphics larger than that, I’d bet. So for most people that gives you a solid array of formats to work with (ODT is OpenOffice, best used with LibreOffice these days) without having to hunt down and install additional tools.

You can get PDF available as well, but that’s going to be a product of the LaTeX typesetting system (.tex), and so it is hidden unless you have that installed. LaTeX is an alternative to word processing workflows, commonly used in the sciences and mathematics. But it’s a very capable general purpose design engine (it’s what we use for our manuals). You will probably notice a number of the threads around here have to do with that system, and that’s where things can get awfully technical. LaTeX does not have a learning curve, because that implies things eventually get easier. :slight_smile: It does have a very rewarding power spike however, for those that are willing to put the time into learning it.

If you just want a dirt simple PDF, I’d recommend ODT or DOCX and creating one from your favourite word processor in five minutes.

It seems I will have to learn Pandoc to make such conversions and I’ll have to assess whether that is worth the time for me.

There is a simple installer for Mac and Windows. Run that, restart Scrivener, and you’re done. You could learn it, and you may eventually want to, but that is not necessary. The DOCX it makes is fully styled, so you could even just change appearance that way—although I will say that customising its stylesheets is pretty easy to do, and worth looking up in its documentation if you have strong preferences that deviate from the defaults.

Fundamentally, if I write using MMD, it seems that to get all of the conversion possibilities Scrivener has native to using it’s rich text formatting, I will have to use Pandoc. Pandoc would not be necessary for .odt, .fodt, and .tex files. Do I have that right?

For the most part, that is correct. The software does have a simple Markdown to RTF conversion option, which you’ll find in the Options tab for its built-in formats. However it has notable limitations, and frankly I’d rather spend the time learning how to do things with native converters than learning Scrivener’s more complex rich text compile system, only to find it can’t do something you really wanted. And as rms says above, you often don’t have to learn much, if anything, particularly if you aren’t picky and are happy formatting in post.

Another advantage is that in most cases the actual quality of the document you’ll be getting with these converters exceeds what you get from Scrivener itself anyway—and I would say the learning curve with either is probably about the same. Compiling with Markdown is a lot easier in Scrivener, because there isn’t much to it, it is deferring the hard work of document production to these conversion tools—which evolve and get better over time on their own. You will be investing time one way or another, and if your preference is to write in Markdown, I’d say the answer is straight-forward.

Plus, I like to think beyond one tool. Learning how to wield Pandoc or MultiMarkdown on their own means all of my writing output can be improved, not just the stuff I start in Scrivener.

3 Likes

The “entire chapter” is quite sparse in my opinion. It needs an end-to-end workflow, not a series of hints and pointers to various sources.

If you do this, do not write rich text italics or bold. You’ll lose them in Markdown compiles.

There is a conversion switch that makes it possible to use the Markdown outputs with no knowledge or use of Markdown itself. It does work better with a styles-based approach, but basic stuff like bold and italics works fine.

But for those wishing to mix Markdown and rich text, the best approach in my opinion is to embrace styles for what rich text you want. There is little overhead in using Emphasis instead of raw italics, and so forth. It’s a good way of working all around, in my opinion.

You once spent three days telling me how to make hybrid work, and it never worked. Remember?

I don’t recall that specifically, but I kind of remember there being an edge case, or trying to get it to work a certain way that it isn’t meant to. But as an umbrella approach, it’s not correct to say it doesn’t work—the user manual project is a hybrid project, and it works fine. Very few of my projects are pure Markdown in fact.

Like I say above though, when we speak of hybrid projects, we mean combining styles with native Markdown, and optionally whitespace conversion for those that prefer to keep paragraphs adjacent while writing.

Then you don’t mean I can hit ⌘I for italics and get that to survive a hybrid compile, but it does survive if I use an equivalent character style?

If using that shortcut is meaningful to you as a way of adding emphasis to a document, then by all means bind ⌘I to the style you wish to use. But yes, to reiterate, the production of Markdown from the editor by default ignores formatting, excepting those cases where there is an unambiguous desired result, like a footnote or image. Italics, all by itself, is ambiguous in a semantic document, just as 24pt text would be.

I’d argue it’s not less semantic than h1 from a Markdown perspective. You could use it wrong in a sense like someone might use h1s to produce “nice big text”. But ambiguous?

By that I mean, what are italics being used for? Is it a film title, a foreign language phrase, someone shouting? We can discern these ourselves from contextual cues, so when I say ambiguous, I mean from the standpoint of how software is meant to interpret the use of a particular type of formatting (keeping in mind italics is not emphasis in RTF). If it is being thought of and used for <em>emphasis</em>, then all right, but we can’t know that from the formatting itself and software is bad at discerning context.

Moreover I would say it keeps things a bit more clear, in terms of anticipating how the software is meant to work, if we keep conversion limited to:

  • Things that only have one logical output and one intention in its usage in the editor (an example of something that has one logical output but an ambiguous usage in the editor are links. One might use links purely for the benefit of the writing process, with no intention of them being exported as functional).
  • Things we “program” ourselves into the compiler (styles).

If we sweep aside all ad hoc rich text formatting that does not fit that criteria, then it leaves those tools open-ended in how we use them as writing tools, rather than formatting tools. I like to use italics and bold to indicate editorial concepts in my writings, with the expectation that I’m not going to end up with Markdown asterisks littering everything. If that’s what I want, then I will either type them in or use styles (hybrid).

1 Like

I know what you mean. It’s just not ambiguous (or, shouldn’t be). You may use italics (RTF), em or i (HTML), * or _ (Markdown) semantically “correct” for emphasis. Or something else. It should translate correctly back and forth anyways, because it doesn’t care what you actually wanted to express.

Now that I’m thinking about it… is there a way to specify other HTML elements for styles, like already possible in Scrivener for h1–h6 headings? This could solve a lot of “compiler confusion”. You could tell the style to be “em” and that’s it.

There are a few built-in translations. If you double-click on the “Basic Multimarkdown” compile format to take a look at its settings, you’ll see what I mean in the “MultiMarkdown Options” pane. The other built-in behaviour is translating the Format ▸ Paragraph ▸ HTML Header Level setting to hashes, which I believe you’re referring to.

Beyond that, if you wanted to make a style only emit <em> then you could do that in the Styles compile format pane, via the prefix and suffix fields. Thus, you could make a style that encloses text in <span class=“film-title”>…</span>, or the wide variety of elements supported in native HTML as well, that aren’t supported by Markdown syntax. And at that point I feel we’re getting into the heart of Scrivener’s advantage as a hybrid tool, where you can go beyond Markdown without the clutter of raw final format syntax in the writing interface.

1 Like

Yes, that’s what I meant. You can assign the header-levels there directly. I’m sure there’s a reason why it works this way for headings and not for "em"s, for instance. I know how to navigate around it (compiler styles, etc.) But that’s what I mean by “confusion”. It’s not always obvious or intuitive, where to manipulate what. Or why something else somewhere else. And good look “just” assigning ⌘I to a style in Scrivener (I know how to).