Help w using markdown files (from an Obsidian user)

Hello there, I’m currently doing a trial of Scrivener with a view to purchasing it on MacOS.
I’m an Obsidian user wanting to use the power of Scrivener to turn my library of markdown notes into a final draft academic papers. I’ve changed the default settings to plain text and the default file type as .md. But I don’t understand how to finish the rest of the set up.
Example: I have a long (30,000 words) dissertation that is formatted in markdown that I want to open in Scrivener to be able to restructure while keeping it in markdown format. How can I set it up so that it detects my #Headings and ###Headings etc. as different chapters and produces an outline that I can click and drag to restructure? I’ve searched online quite a bit, read posts, tutorials and discussions on this forum but I still haven’t been able to figure it out.

Try File > Import > Import and Split, and in the dialogue box, make sure ‘Options’ is selected. The actual options will change depending on which file type you’ve selected — so when you highlight your markdown document, you’ll see an option for Split and Structure using Markdown headings in the text.

If want to convert the documents to RTF formatting, then tick ‘Convert Markdown’, otherwise untick it and the markdown will be preserved. Either way, your document will be imported into the binder with your outline structure intact and the Headings as the document titles.

Does that help?

Yes hugely! Thanks very much.
Two specific questions:

  1. I successfully imported a MD file which was split into its structure headings. But some headings were missed so sections are accidentally spliced together. I corrected the # formatting to smoothe it out but when I Compile, then import and split that newly compiled file, it goes from the left project to the right project. ANy idea what might have gone wrong here?

  1. When I make changes like that in the text using, for example, ### to make a Heading 3, what’s the quickest way of getting that to reflect in the structure of the document? The only two ways of doing it is to manually click and drag and edit the structure with the cursor in addition to the typed text, or to Compile and then re-open separately the entire project. They both seem quite cumbersome so wondering if there’s an obvious easy way of doing this.

Thanks again for your help

It’s a bit difficult seeing exactly what’s going on in your screenshot, but my best guess is that the second import is doing exactly what you asked it to — it’s splitting the document accordingly to the markdown structure.

When you imported it the first time, you had lots of markdown headers, and the process translated that into the binder structure you’ve seen on the left — by creating a new document at the right level, with the appropriate indent and then removing the # mark.

So when you compile it and reimport, it only finds the ‘missing’ hashmarked titles you’ve added the second time. Effectively, you’re changed the structure of the project completely.

This is tied into to your second question. Instead of adding ### for the Heading level 3 where it had been missed, the normal way to create a new document/heading in the structure from a larger text would be to highlight the heading and choose Documents > Split > with Selection as Title. As the name suggests, this splits the current document in two, with the selected text as the heading for the new segment. You can then drag and drop the new document into the correct level in the Binder to reflect your chosen hierarchy. Of course, in this case, you’ll have to remove the ###, but normally that’s not a problem. (You’ll recognise that this is just doing manually what the Import and Split process does automatically.)

In fact, you could also get the same effect by highlighting the second part of the larger text, cutting it, creating a new document and pasting the cut text in, before giving the new document a new title, but ‘Split with Selection as Title’ is quicker…:slight_smile:

Perhaps a bit of background may be useful. In general, there are two ways of dealing with Headings in Scrivener (whether you’re using markdown # Headers or RTF style formats).

  1. You put them all in the text and just use the names in the binder as a memoire to you about the content of the file — when you come to compile the document, the document names from the Binder are ignored; or

  2. You don’t have chapter/scene/section titles in the text — they’re all in the Binder titles and structure.

The second option is much the preferred solution, because it means you don’t have to worry about numbering the titles — in compilation you simply set a numbering scheme and the compilation process adds the right numbers depending on the hierarchy in the Binder. In your screen shot you’re going to have to renumber the titles if you reorder the chapters/sections. If you use method 2 then all you need is the section title and Compilation will sort out the numbering for you. That means you can move the sections around at will with our renaming, which is one of the major features of Scrivener.

In general, Scrivener is designed to work best when you use the binder to divide your document in to the smallest ‘chunk’ appropriate to your document: it could be a scene for a novel, or a subsubsubsubsection for a technical manual — the point is, the more your binder reflects the structure of the document, the better you can use Scrivener’s many planning and organisation tools. You binder then contains not just the complete text of the project, but it’s also a full outline and card index of synopses at the same time.

If you haven’t already done this, could I suggest you take an hour or so and do the Interactive Tutorial (on the Help Menu) — it will show you the main reasons behind the way Scrivener is made to work, and it will save you a lot of time in becoming effective with the program.

HTH and good luck!

I’d like to add that you should avoid Obsidian’s inline footnotes—^[inline footnote]— because they are different to the MultiMarkdown footnotes—[^inline footnote]Scrivener can handle.

Not to worry about this - Obsidian handles both but I’ve only ever used its standard footnote [^1] rather than the inline footnote ^[1]. Thanks for the reminder though that’s always worth mentioning :+1:

1 Like

Scrivener uses RTF, not plain text, and it doesn’t offer the best markdown-centric environment to work in or compile from. You can use markdown in Scrivener, but it is not a great experience.

If you still need the flexibility of markdown and the security of having future-proof files that are also editable by other apps, you could keep the work in Obsidian and use Pandoc or, if you’re on a Mac, Marked2 to output your writing.


Hey Brookter- thank you SO much for your comprehensive answer. That is incredibly helpful and clarifying.
Of course you can suggest that, and I will definitely take your advice and spend an hour on the tutorial.
One quick question: is there somewhere I choose option 2 rather than 1 in settings somewhere or it’s just a matter of only making edits via 2 and not 1 myself? Similarly, would the idea be that ideally I’d ultimately end up with a Scrivener project that didn’t show any # Headings because they’re all in the binder, and then it’s when I Compile to a MD format that Scrivener would then put the # Headings back in?
If you want to say ‘wait til you’ve finished the tutorial to see if it answers those 2 questions’ then please feel free!

Thanks very much Merx. Yes I’m happy to keep output my final docs with Obsidian or command line Pandoc. But it’s the text restructuring that Scrivener excels at for me and I’m struggling to work out if I’ll be able to use Obsidian for my first draft writing, then restructure in Scrivener, then back to Obsidian for final output/conversions. Do you think there’s a way to make this work well? I’m willing to pay for both Scrivener and Marked2 if it means getting the workflow right.

I am 100% fixed on using markdown for precisely the reasons you give (future proofing, not being locked into propriety formats etc). For me if I have to choose between Scrivener and Markdown, it’ll have to be Markdown every time. I’m hoping not to have to make that choice and to be happily purchasing a Scrivener license before long!

RTF is not a proprietary format, and it is plain text under the hood—though with masses of formatting instructions in plain text. So if push ever came to shove you can extract all your text using a text editor.



You don’t need to choose between markdown and Scrivener at all — many people are very happy with the combination.

In fact, the Scrivener manual is actually a Scrivener project based on a hybrid markdown / LateX workflow and most documents aren’t as complicated as that document. If you’re interested, you can download the Manual Project on the website and see how it’s done. Warning – it uses a lot of advanced techniques which are beyond me… The Manual’s author posts on here as AmberV — he’s written quite a lot about using markdown on the forum so it might be worth searching for some of these posts. There’s also a dedicated Category on the forum (Markdown & LaTeX - Literature & Latte Forums) which is well worth checking out for advice.

What Scrivener doesn’t do is provide visual confirmation of the formatting as you write: e.g. you only see **bold** not bold in the Editor — you can use Marked 2 in conjunction with your project if you want that. They’re designed to work together.

An alternative is to explore Scrivener’s Synchronised Folders feature, which allows you to sync the existing documents in your binder with (and create new ones in) a folder and work on them in a markdown editor (including Obsidian), — this allows you to use all the organisational features of Scrivener but still have a more ‘targeted’ markdown environment for the actual editing / writing, or collection of notes. It’s also a good way of working on the project on an iPad without needing to buy the iOS version of Scrivener.

TBH though, given that you’re only just starting with Scrivener, I’d spend a bit of time getting a bit more familiar with how it works and then you’ll be better able to assess if and how to use the synchronised folders feature.

As for your question — there isn’t a ‘setting’ for my Option 1 or 2. You just use one method or the other as you write the documents.

And yes, you’re right, in this method 2, one of the available compilation methods does exactly that — it puts the relevant number of #s before the chapter / section number/heading when you compile.

I hope this helps, and good luck!