I’m trying to “sell” using markdown to my team to convert our custom cms which currently parses word processing docs. Hidden formatting in the docs often causes unintended formatting issues, and the importing code needs (but doesn’t always get) frequent updates to keep it working reliably.
But we need change tracking, and ideally it needs to be usable on both Windows and Mac. Does such a solution exist? Web-based or an app would work. Thank you!
Brett Terpstra’s invaluable Marked 2 also interprets and displays CriticMarkup properly – you have a choice of seeing the markup (strikethrough, insertion, etc.) or incorporating the changes.
That’s said, it may not be as seamless as Google Docs or MS Word if you’re a heavy user of change tracking.
Git is specifically designed for tracking changes in code. As code and Markdown are both plain text file formats, git is very well suited to using with Markdown. That said, there are a few concerns.
Git tracks changes by line, not by word (ex: line 42 changed). This can be a problem in Markdown if you use soft wrapping. In other words, if you type your paragraph as one long line of text and allow your editor to soft wrap the text in its viewport, git will simply tell you that there was some change in this paragraph and you will still need to figure out what that change is. On the other hand, if you use hard wrapping (inserting hard line breaks at the end of each line), then git is much more useful. As it turns out, any good code editor will include tools for hard wrapping lines. However, everyone who edits your documents must use those tools for it to work well. And I haven’t seen those tools in Markdown (only) editors.
Most code editors also have integration with git. However, they only show git information, they generally don’t provide any way to interact with git. Therefore, with a few exceptions, your document authors/editors will need to interact with two programs: the editor and the git gui/cli. Getting nontechnical people to use git can be a hard sell.
As I understand it, there are some addons to git which can show changes per word, etc., but they are not built in and you would need a tool which supports them. That would significantly limit which tools you can use.
Despite all of the above, I personally use and prefer git. But then I’m using it for my code projects and use Markdown to write the (technical) documentation for them. That said, getting others who contribute to my opensource projects to submit well-formed changes to the documentation is always a challenge.
I had forgotten about CriticMarkup. It really looks like a better tool for Markdown than git and according to the documentation appears to address all of the concerns I mentioned regarding git. That said, I won’t be using it as my Markdown documents are included in my code projects which use git. But for a Markdown only project, it could be very useful.
Waylan, Thanks for the info about changes being indicated only by line. I didn’t realize that was the case. But unfortunately I don’t think that would work in this situation. On top of that the paragraphs written and edited are typed as a continuous line, so git would indicate the entire paragraph had been changed somewhere, rather than which words were changed. Oh well…
The diff will still show which words have been changed in the line, it just won’t be as neat as if the text was hard-wrapped. It’s definitely still usable though, from my experience.