I am now going to document the large SoilWater-ToolBox SoilWater-ToolBox by attempting to use Documenter and I am looking for a Markdown software free or paid. I use VsCode but there does not seem to be any extensions which will meet the following requirements.
- Can handle LaTex
- User friendly where one can easily see all the different format options
- Allows personalisation of the website
Many thanks for providing me your preferences?
@PetrKryslUCSD Which one was less of a poison for you?
For markdown I actually stick to VS code (when I program in VS code), or sublime text (when I program in sublime text). I sometimes switch between those two. Sublime text has a package for writing markdown. VS code has an extension for the same, which also does nice preview in VS code.
Personally I like “Markdown Preview Enhanced” in VS Code. But if you really want WYSIWYG… Maybe Typora?
FYI, I would like to add Mark Text to the list. It is an open-source WYSIWYG Markdown editor.
Without starting a war or hijacking the thread, which one do you like for Julia? do you also program Julia in Sublime?
@amrods I program in VsCode but I am sure that there are users who enjoy Sublime so if there is Markdown software in Sublime it is fair to provide feedback.
I admit that I like ST (I use ST4 at this point). But in some aspects VSCode is at this point ahead in terms of functionality. For instance code evaluation or debugging.
Why would you want wysiwyg?
Not all in my team are programmers and therefore I would need a writing tool to document the large program which is user friendly I guess.
Indeed… by design, in Markdown the code itself is almost WYSIWYG…
If they can’t edit as simple source as markdown, they shouldn’t be touching the documentation.
That is a bit harsh, isn’t it? Markdown is a nice and simple format in theory but it is also underspecified (in fact the original author refused to specify it) and parsers can behave in surprising ways.
Speaking of surprising, people can be surprisingly set in their ways in terms of using computers. So if you want an expert in their field write some docs for you, you should let them do it their way. Especially if their time is expensive. In the end you can also let them write in Word and convert to Markdown via Pandoc.
TL;DR: Don’t judge people for not knowing the tool du jour even if it is simple.
FWIW, one of Typora Markdown editor’s strength is that it can import / export
docx files in the GUI by calling
pandoc. LaTeX-like math expressions in Markdown will be converted to MS Word math expressions as well. (I’ve not tested the other way around)
This simplifies the workflow a little bit when I (writing LaTeX-like math expressions in Markdown) and my collogues (using MS Word) have to exchange documents.
I would argue markdown is so simple, it has about the same learning curve as any wysiwyg alternative. It’s not about judging people, it’s about not spending energy dumbing down a task that arguably shouldn’t be done by someone who can’t operate a text editor. If someone can’t write markdown source, they can’t read Julia source, and so they shouldn’t be documenting the latter.
No, but one could use
git for version control.
Another option is Dropbox Paper. Much better than Google Docs, it’s markdown-based and WYSIWYG. Support LaTeX and syntax highlighting, and you can export pdf, docx, or markdown. And you can “comment” the same way as in Google docs.
Really, it’s weird to me that anyone would prefer Google docs over this.
One caveat for Dropbox Paper: Though you can use latex environments that create multi-line equations, the LaTeX input currently seems to be required to have no newlines:
This may be out of date; if not, I hope they’ll add multi-line LaTeX input before long.