Hi , I am planning to write a technical IT book with scrivener.
This will be a multi hands part , and for this I would like to find a way to permit sharing, forks, and contributions.
The envisages way was to sync out to Markdown, and gitHub the Markdown files pieces.
so whoever want to do some contribute, review, can fork it , modify, and I can plug back in.
Besides, the ultimate publishing form will be some markdown for online publication ( on top of a PDF for offline consumption)
has anyone already experimented this, (Scrivener <> MD<>github) and could share feedback ?
Many thanks, dear community
note: I am not planning to share the sciv file in github direct.
note: granularity of files are smaller than chapter, nearly 1-3 page level
Some people are quite happy with use the File/Sync/with External Folder feature for collaboration of this sort. You can set the output to be plain-text and even set the extension to .md so that everyone’s text editors can automatically use syntax highlighting if available. Changes made to the external documents will be synchronised at a paragraph level of granularity as needed. The principle drawback of the feature (for collaboration) is that the output is a folder with a flat list of files, one for each node in the outliner. For a large technical book that could be hundreds of text files. So long as file names are kept informative and concise, it shouldn’t be too much of a bother as they will be in book order if you enable the prefix numbering option. The other minor drawback from your side is that it means you won’t be able to use internal Scrivener Links within the text (well you can, but you risk losing them whenever you sync); use References instead. Inline (not inspector) annotations and footnotes will be converted to plain-text syntax, so your colleagues will be able to see and edit them, as well as add their own comments.
So, you would just use git to commit the sync folder and go from there. I’ve never actually heard of anyone doing that specifically, but in principle that is only a more robust and less automatic version of what other people do use Dropbox (and similar) shared folders for.
I will share my tips here ,for the memory; as I find them :
1/ inserting new cards, especially early in the text ,will change all the text file ( the synced one), as the number indicate the order.
as a result, a git commit is not enough, but a git add is needed, as all these files have changed names, hence considered new ( git add . at top add all)
2/ I wanted to add the card number to appear in the pdf, so people can find the corresponding (synced) file more easily ; by reading the pdf , seeing the card #, and then jumping to file #
I had the belief I saw somewhere an option to display this card # , I looked in compile and prefs but did not found it .
any help welcome …
(I am not talking of the view card number for dashboard, I d like to see it in the compiled pdf)
There is not a specific option to number outline items in compile, but rather a large toolset of features which can be used to create various numbering schemes. This is all primarily done using the Formatting compile option pane, in the title Prefix/Suffix fields (within the “Section Layout” button) for the particular icon type and outline depth (by default, all depths will be addressed by one setting, read the documentation on the Formatting pane for details on how to use it).
In conjunction with these tools for injecting text into the compile stream, you can use the auto-number counters, which can be found in the Edit/Insert/Auto-Number/ sub-menu, or via referencing the Placeholder Tags cheatsheet in the Help menu.
But do note that in general compile is not a very good technique for round-trip collaboration because it by definition destroys the Scrivener specific features of your outline by compacting it into a single file. Once it is in a single file, it is not possible to magically import that back into the binder and have it update all of the pieces of the outline that were used to create it.
If the folder sync method is not good for you, and the thought of using copy and paste to update your project whenever there is an external update does not appeal, the only real good solution to this problem is for everyone to be on Scrivener, working out of the same project on a rotation. It’s a great program for working that way—we do it a lot ourselves internally for various documentation and development notes.
thanks for this detail support, I learned a lots of new features.
I was able to insert variables in titles, i tried - <$n>-<$sn>-<$position> - <$parentposition>
but I cannot find the one I would like : the binder position.
as far as I understand, the files synced out are (optionally) prefixed with a number the binder position. there is another number in the filename too, which I guess is the card number.
e.g. : 39 Part 2 A ledger program -29-.md
does it exist a variable reflecting these ? ( I would say so , as they are used in the sync number)
this would be useful for people reading the pdf to directly spot the associated synced md fragment.
Well, since you are using Markdown, why not compile to plain “MultiMarkdown” with titles turned on for all types in the Formatting compile option pane. This will produce headers in the output, set to outline depth. Then you can use File/Import/MultiMarkdown Files... to bring the edited document back in, and it will be split up automatically and into the original hierarchy. Additionally any heading work done by your colleagues will be updated in the Binder import, too.
The main drawback, as with all other compile/import/compile/import cycles is that you lose all of Scrivener’s internal features like Scrivener Links, and comments/annotations as well as footnotes (though the latter will be converted to MultiMarkdown format, so they will not be lost, just converted to plain-text).
But in regards to that number, it is just the internal ID; a unique number assigned to the binder section when it was created. They can thus be all out of order, and the application does not expose this number in the UI anyway, so it would be work-intensive to try and use it as a cross-reference.
: the binder position.