Basic use of Markdown as primary writing format in Scrivener

Scrivener Markdown & LaTeX
,
8

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
9

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.

10

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

11

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.

12

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

13

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.

14

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?

15

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.

16

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?

17

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
18

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.

19

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
20

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).

21

By default? How do we override that default?

22

Italics is one typeface of a font family. If a family has no italics typeface or you didn’t install it, you don’t get italics. That’s not particularly ambiguous.

23

Right. I have no trouble binding shortcuts.

24

Do you mean the asterisks, hashtags, etc of markdown being visible in the editor?

Those marks no longer have to be visible:

intro

Merx

1 Like
25

All this talk in the 21st century of Markdown code and dialects reminds me of the thrill people had in the 20th century (late 1980’s as I recall) when people found writing tools other than Wordstar, Electric Pencil, WordPerfect, and DisplayWrite to avoid writing with codes. Those were the days.

1 Like
26

I’m referring to the fact that the formatting itself is open to multiple interpretations, and software isn’t good at that. I am not seeing how this relates to whether this or that font is installed—save to reaffirm that this kind of weird and fragile stuff is why I use Markdown instead of fonts to relay information while writing.

Oh no! I don’t consider that to be clutter at all. To put emphasis to my quote, I was referring to “raw final format syntax”, or what we use Markdown as a front end to produce. Typical Markdown editors work largely within the confines of the specification, and that means creating richer documents from it most directly requires putting the syntax into the writing space, in one form or another.

I personally have no problem seeing Markdown in the editor, and in fact far prefer it. I never had any affinity toward editors that hide it or use syntax highlighting to diminish the legibility of markings (I think Typora was the first to do the former). And so I don’t use Scrivener’s capacities to do much of that either. I get there are folks that do prefer that, and treat Markdown more as RTF is treated (you never really see it), but it’s not for me.

To return and expand upon what I’m referring to, there is an objectively clear advantage in Scrivener’s court when it comes to creating richer documents—those that require extended semantics:

In the top left we have Scrivener, where the gold italic heading is in fact just a Scrivenings title, not styled text (I pretty much outline exclusively, rather than putting hard-coded heading depths into text). The list contains two different styles, one of which is using a feature to pull data, a platform-specific keyboard shortcut in this case, from another outline node via a hyperlink. Replacements are also in use to take easy-to-type shorthand and turn it into format appropriate symbols later. The two example styles here are interface labels, for menus and shortcuts, and preference labels, depicted in bold, dark brown text in the output. (There is also a third style, used purely aesthetically to add a hanging indent to my Markdown list.)

On the right we have Typora, which as mentioned is one of the Markdown editors that strives to hide the fact that one is using Markdown while writing. What we are doing with styles in Scrivener is extending what the Markdown specification itself supports (using an open-ended convention supported by the two conversion engines Scrivener integrates with). We are using the same exact approach in Typora, but as it lacks Scrivener’s hybrid mechanisms, the full raw syntax must be present in the writing space.

Since there is no Markdown for doing any of that, using a simpler editor we’d have to type all of the raw code by hand, or devise macros or text expansion shortcuts to help us do so. The result, as you can see in the top right, isn’t pretty. We have language target code that isn’t recognised by Typora printed into the output as regular text, alongside code spans where the LaTeX syntax itself inserted. Since these types of editors tend to not have much by way of heavy-duty book production features, we have to do more manual labour, specifying symbols codes by hand and doing more static content creation. This is in fact being a bit generous, as to really pull off having two PDFs, one for PC and one for Mac, we’d need to have conditional LaTeX code around each keyboard shortcut that prints a different output depending on a variable we defined elsewhere (as most such tools only have simple export, no processing, automation or compiling).

We are also being generous in that this is one single-purpose output being exhibited. If we were intending to produce two or three different outputs, say PDF, ePub and DOCX, then around each interface label and so forth, we might have to write and edit around stuff like this:

1. Open project settings with the <span class="interface">`\interface{`{=latex}`<w:r><w:rPr><w:rStyle w:val="Interface"/><w:rFonts w:ascii="Linux Biolinum O" w:hAnsi="Linux Biolinum O"/><w:b w:val="false"/><w:caps w:val="false"/><w:smallCaps w:val="false"/><w:color w:val="auto"/><w:spacing w:val="0"/><w:sz w:val="24"/></w:rPr><w:t>`{=openxml}Project` ▸ `{=openxml}`{\menusep}`{=latex}`&nbsp;&#9658;&nbsp;`{=html}Project Settings`…`{openxml}`{\ldots}`{=latex}`&hellip`{=html}`}`{=latex}`</w:t></w:r>`{=openxml}</span> menu command (<span class="interface">`\interface{`{=latex}`<w:r><w:rPr><w:rStyle w:val="Interface"/><w:rFonts w:ascii="Linux Biolinum O" w:hAnsi="Linux Biolinum O"/><w:b w:val="false"/><w:caps w:val="false"/><w:smallCaps w:val="false"/><w:color w:val="auto"/><w:spacing w:val="0"/><w:sz w:val="24"/></w:rPr><w:t>`{=openxml}`{\sopt}{\scmd}`{=latex}`<img src="opt.png" class="shortcut"/><img src="cmd.png" class="shortcut"/>`{=html}`⌥⌘`{=openxml},`}`{=latex}`</w:t></w:r>`{=openxml}</span>).

In case it isn’t clear (:laughing:), this is just the first bullet line in the original sample text. I’m not sure if a slick editor interface helps much:

This is opposed to the top left Scrivener screenshot, which never changes, because one style can generate a hundred different kinds of documents. It’s not an earth-shattering idea to be fair, it is after all how Markdown itself works in conjunction with tools like Pandoc. You take one simple input and leave the specifics of output to conversion. The difference between Scrivener and just about every Markdown-focused editor out there is that it is tuned toward stuff like the above, in acknowledgement of the fact that authors are going to need more than HTML and a few scattered goodies.

Don’t get me wrong, these other types of editors have their uses—I use them myself, along with general purpose text editors with Markdown plug-ins. They address areas I wish Scrivener did better in, namely in syntax highlighting and typing aids. But hopefully it is more clear now what kinds of things Scrivener brings to the table as a larger scale Markdown authoring environment. Obviously one wouldn’t use a tool like Typora, or even most any Markdown-based editor, to do this kind of stuff in the first place, so these clutter examples are a little artificial in that sense—but that’s kind of the point.

More complex examples aside, to return to a simpler example discussed above, we can have that same style producing <em>…</em> in HTML (though you might as well just use asterisks in the prefix/suffix fields) doing something else entirely, like \emph{…}, by simply swapping which compile Format you use.

I realise we’ve strayed a bit from the original question, of what basic use of Markdown is like in Scrivener, but hopefully this helps with the overall question of which tool is best for the job.

And by the way, for some projects I use Scrivener’s external folder sync feature in conjunction with Markdown editors for the writing. I get the best of both worlds, when I can, and when I need a more complex document like the manual, I stick with Scrivener for its additional editor level features.

6 Likes
27

I’ve finally worked out a workflow of writing in Scrivener, compiling to markdown, and then using Pandoc to covert markdown to docx and pdf. I really don’t know what I’d do without Scrivener’s flexibility in all this. Today I was trying to figure out how to ensure that text after an element (in my case it’s usually an equation) would not automatically indent. In LaTeX one can use “\noindent” for this, and Pandoc will pay attention to that when you ask Pandoc to convert from markdown to pdf. But it won’t pay attention to it when you ask it to convert from markdown to docx. So what to do? Well, Pandoc allows one to create a reference docx file for any conversion to docx. So, I created a new style in that reference doc called “Body Text 2” and I imposed a “no indent” rule on that style in the reference doc. Then I made a new section type in Scrivener called “Noindent”, and I placed all the text I wanted not to be indented after an equation into sections of that type. Finally, I used Scrivener’s compile pane to create two new section layouts, one that adds “\noindent” as a prefix to the Noindent section types, and one that adds a prefix and a suffix that Pandoc uses to impose the “Body Text 2” style when converting from Markdown to docx. This way, if I want to use Pandoc to convert markdown to pdf, I tell Scrivener to apply the “\noindent” prefix to the Noindent section types; if I want to use Pandoc to convert markdown to docx, I tell Scrivener to apply the custom style command instead.

Scrivener never ceases to amaze me.

6 Likes