Github markdown preview?

Hi folks, I’ve not been able to find examples of this, but figure some folks must be doing it. I want to use scrivener and github for my project, and would ideally like to figure out a nice way to take advantage of githubs built in markdown previewing for my collaborators to be able to look at versions of pages nicely right on a github account. Is anyone doing this and if so, do you have suggestions? FWIW, I’m also a coder, so if need be i could write a script or maybe hook up some kind of git hook to render previews in a different directory. But I’m brand new to this so don’t want to reinvent wheels if I don’t need to. thanks!

Scrivener is fundamentally a collection of XML and RTF documents. When you write markdown in a document in your Scrivener project, it is saved as an RTF file and not a plain text file. GitHub’s markdown processors won’t deal with that, to the best of my knowledge. And because of the internal file structure, even using Git (or other version control) to allow multiple collaborators to work on the document is asking for file corruption.

Devin is correct regarding the scrivener document bundle, so the options you need to consider are to either make use of Sync (File▶︎Sync▶︎with external folder…) to plain text files, or full markdown compile to a folder. The folder will be under git control in both cases.

The benefit of sync is you can do two way, i.e. a collaborator could fork and pull the plain text files and you could merge back. BUT sync doesn’t utilise the power of the compile engine, and you can lose scrivener specific formatting / features.

The benefit of compile is, well compile is exceptionally powerful in transforming Scrivener features into markdown and then trigger post-processing. Github flavoured markdown (GFM) doesn’t support as many features as MMD/Pandoc, but you can selectively handle this in the compile. I use Pandoc for everything, so if I was to build a workflow for sharing via Github, I’d use Scrivener compile > Pandoc > GFM (as Pandoc can write GFM). Scrivener produces a single file, but it is easy to split into separate MD files then run Pandoc on each file individually.

Hi iainduncan! Sorry to be so late to the party, but it’s really simplistic so set up what you’re talking about. There are two different setups, depending on if you want to be able to “sync both ways”, i.e. if changes on GitHub should show up the next time you open your Scrivener project. Both alternatives start with a download of GitHub Desktop, so you don’t have to create repositories on the command line.

Alternative A - Nicer GitHub preview, but one-way ‘sync’

  1. In Scrivener’s File menu, choose ‘Export’ and select ‘multimarkdown (.md)’ as the format. Under options, make sure the .md extension is used and ‘Convert rich text to markdown’. Create a folder somewhere and hit the ‘Export’ button.

  2. Fire up GitHub Desktop and create a new repository, select the folder you just exported everything to and in the GitIgnore option at the bottom of the window, choose ‘Scrivner’.

  3. Publish the repository to your GitHub account. Now you have beautiful markdown previews of what you have written available for everyone that has access to your repo. And the ‘folder structure’ of your Scrivener Binder is translated to folders on GitHub. (Which makes it a good policy to have chapter names - or whatever your binder folders represent - that have some kind of easy ordering lettering built in.)

Alternative B - GitHub preview, and two-way ‘sync’

  1. In Scrivener’s File menu, choose ‘Sync’ instead and select ‘multimarkdown (.md)’ as the format. Also make sure the files are prefixed with numbers. Among the options, select exporting on close and checking on open. Hit the sync button.

  2. Open GitHub Desktop and do the same thing as in the first alternative. Publish the repository to your GitHub account.

  3. Because of Scriveners’ less than optimal treatment of its own Binder, you will not retain the ‘folder structure’ (Yes, ranters, we know that Binder folders aren’t that…i.e. folders.) But the numbering will put stuff in the right order and with some pedagogic naming of parts, chapters et al you can still make the GitHub repo navigational.

  4. Instead, the big advantage of this alternative is that if you want to change or add text on GitHub you can now sync that with your Scrivener project! Or, if you have the strange inclination that writing actually in a majority of cases (Book = writer/editor, Articles = journalist/editor, Film/TV = writer/co-writers/director, Papers = let’s not go into how many) is a collaborative exercise, collaborators input can also be synced with your Scrivener project making this a maybe roundabout but still Holy Grail of collaboration ‘in’ Scrivener.

  5. On GitHub your or collaborators add stuff. You or more people with the rights merge what should be merged. Then you fire up GitHub Desktop and it will automatically want to ‘sync’ down the changes made on GitHub.

  6. Next time you start Scrivener, it will look for changes in your ‘sync folder’ and import them. Carefully marking them so you can see what have changed.

Et voila!