Does Scrivener really generate Markdown?

[George_Entenman]

I’ve tried unsuccessfully over the years to get Scrivener to generate markdown so that it could truly be the writing tool that I want.

This week I decided to bite the bullet and see what I could do in spite of a manual which is good, but in which I have trouble finding complete explanations.

HEADERS

So far, I’ve figured out how to generate H1 and H2 and H3 headers.

HYPERLINKS

Hyperlinks come out okay.

LOCALLY-STORED IMAGES

Images stored locally seem to work okay although I’d like to be able to keep their leading pathnames: copying them is not the behavior I want.

REMOTE IMAGES

But I cannot figure out how to show images stored on remote servers, something that I almost always do with markdown.

Markdown makes it extremely easy to display remote images.

If I type the markdown into Scrivener, like this

![image from Maker Faire](https://storage.googleapis.com/s3-inbox/zabouti-east-000/server/2016-10-01-Maker-Faire/DSC09700-bw.jpg).

Scrivener messes it up when it generates markdown.

!\[image from Maker Faire\](<https://storage.googleapis.com/s3-inbox/zabouti-east-000/server/2016-10-01-Maker-Faire/DSC09700-bw.jpg>).

Scrivener does not appear to be able to display remote images, much less generate markdown commands for them.

If you want Scrivener to display a remote image, it must first be copied to local storage.

If I insert a local image, say, ~/Dropbox/MyBookFolder/scene_break.jpg, into my document, Scrivener will generate correct markdown:

![scene_break.jpg](scene_break.jpg)

Unfortunately Scrivener also copies the file to the output folder, thereby losing the original file path, which could be very useful for websites. In other words, this is markdown, but not the markdown I want.

PLACEHOLDERS

Reading the manual and watching the Scrivener videos, I came upon the idea of placeholders, in particular, this example from §15.7.5 of the manual.

<$img:~/Dropbox/MyBookFolder/scene_break.png>

So I tried it:

<$img:~/Dropbox/arts-and-science/art-and-photography/photos/2018/2018-08-05-Poet-Fools/_DSC1424-group-photo.jpg>

Output is correct markdown. Almost.

![][_DSC1424-group-photo]

For one thing the image file is copied and not left in its original location. Worse, the file extension, .jpg, is removed. This kind of markdown doesn’t work as far as I can tell.

Finally, I tried a placeholder to a remote image:

<$img:https://storage.googleapis.com/s3-inbox/zabouti-east-000/server/2016-10-01-Maker-Faire/DSC09700-bw.jpg>

No markdown was generated at all!!!

I NEED GOOD, CLEAR HELP

If Scrivener can generate simple markdown of the type I’d like to see, please, someone tell me how. Tell me clearly, preferably with a video. In fact, tell me how you would get Scrivener to generate the following markdown:

[code]# Header Number 1

This is a paragraph inside the first header.

Subheader 1.1

This is bold.

This is italics.

Subheader 1.2

Scrivener is made by Litterature and Latte.

It looks like this:

[/code]

Marked 2 renders this markdown correctly:

https://www.dropbox.com/s/6fqygsjcoej48z2/Screenshot%202018-09-09%2016.37.52.png?dl=0

[nontroppo]

I’ve attached a test project that does 98 to 100% of what you want. One problem you are facing is that you are using the Compile option Convert rich text to Multimarkdown and Scrivener wants you to go ALL or NONE with that setting — you ask it to think the document is only RTF, and everything gets escaped assuming there is no markup[1]. That is why your ![ … ] gets broken by being escaped to ![ … ]

You can use the next option Convert lists and tables to Multimarkdown— BUT you then lose the ability to auto-convert URL links. In my test project with “Convert lists…” set everything works except for the first link in §1.2 Details. So for links with “Convert lists…” you have to also just use RAW markdown (exampled as the second link). But for everything else it “just works” 8) — specifically the external image is passed through untouched and Markdown can use it just fine[2]…

Here is the example, toggle the “Convert…” settings and observe the result:
test.scriv.zip (60.1 KB)

I show a third option: you can use Format ︎Preserve Formatting around your figure, then you can use “Convert rich text…” and get Scrivener links converted for you while not escaping the figure brackets. Technically, you can also use a style with “Treat as Raw markup” in the Compiler style settings too, also demonstrated in the test project 8)

It is worth carefully reading through §21.5 of the user manual for the details…

EDIT: oh I missed it, but the project file used to generate the Scrivener manual is now downloadable, it uses MMD in the hybrid approach to go from Scrivener to a rich LaTeX PDF… Thanks AmberV!!! 8)

---

[1] I have argued previously for a setting to allow the escaping to be toggled, as there are users who may want to mix RTF and markup: http://literatureandlatte.com/forum/viewtopic.php?p=254108#p254108

[2] do note that you cannot display remote images in Scrivener, it will simply treat the URL as a URL, but you can preview it in Marked if you open the .scriv project file or the compiled markdown file…

[George_Entenman]

This is fantastic help with lots for me to study and think about. I’ll get back if I have more questions.

I did search for “the project file used to generate the Scrivener manual is now downloadable” but couldn’t find it. I think I had a copy several years ago but can’t find it either. Can you send me a link to it?

Thanks again for such a quick, thorough reply.

[AmberV]

EDIT: oh I missed it, but the project file used to generate the Scrivener manual is now downloadable, it uses MMD in the hybrid approach to go from Scrivener to a rich LaTeX PDF… Thanks AmberV!!! 8)

You’re welcome.

It’s located among the other downloadable copies of the user manual. Scroll the dropdown to “Mac / Scriv Project / ZIP”, then click the download button.

I’ve got it set up so that it can be used as working project, complete with full compile capabilities (sans some fonts we don’t have the rights to distribute).

[George_Entenman]

nontroppo,

Could I trouble you to send me the markdown output of your test file? I suspect I don’t have the compile settings right when I compile your file.

Thanks,
ge

[George_Entenman]

AmberV

All I can find is PDF versions of the manual. Am I looking in the wrong place?

[AmberV]

That’s the right place. Can you not scroll down in that thing? It’s kind of strange in that it only shows a few options at a time despite having plenty of space to show them all.

[nontroppo]

@George Entenman

Could I trouble you to send me the markdown output of your test file? I suspect I don’t have the compile settings right when I compile your file.

This is with “Convert lists and tables…” enabled in the compiler (note I prefer Pandoc style metadata, which is delimited by — Scrivener generates this with Pandoc enabled in post-processing pane):

[code]

title: Test
author: Joanna Doe

§1 — Introduction

This is a paragraph inside the first header.

§1.1 — Background

This is bold.

This is italics.

§1.2 — Details

Scrivener is made by Literature and Latte. The previous link fails but this one should work just fine.

It looks like this:

Here is some more filler text.

Here is some more filler text.

Here is some more filler text. [/code]

If you try to compile my test project with “Convert rich text…” then you will meet a problem with the styling:

This is a **\*\*paragraph\*\*** inside the *\*first\** header.

This is expected. I am using semantic styles (i.e. I create a style called strong which toggles bold in the editor, but at compile inserts **). “Convert rich text…” doesn’t care about styles, so it escapes the ** inserted by the style, then adds unescaped ** to “convert” the RTF bold it finds in the editor. My strong recommendation is to always use semantic styles, they are much more flexible and powerful; and you can even bind ⌘i and ⌘b to toggle emphasis and strong respectively. The Scrivener manual project uses styles extensively, highlighting how much flexibility is afforded by their use (callout boxes, OS-exclusive text etc.)

[George_Entenman]

Thanks, everyone. I’m still digesting all this and even beginning to produce markdown. I have too many little questions to post here. Maybe I’ll dribble them out over time. And I finally noticed this website, https://github.com/iandol/scrivomatic, that I think nontroppo provided a link to. That looks very helpful.

[AmberV]

It might not be aimed at your particular use-case, but a forum member a while back took the time to put together a journal of their learning process of using Scrivener and Markdown together.