A good editor for technical tutorials on Mac?

Question

I write a lot of tutorials and publish them as HTML. Usually, I type them directly in HTML but each time I use <code> tags to show a code example, I have to manually update the content of the tags (for example, changing > to >).

Currently, I'm using TextMate 2 but am looking for a more efficient way to do this on Mac. How would you approach it (markdown?) and which software would you use?

Thanks!

Answer 1

I would recommend you ReText, as outlined in my answer here:

^{ReText with Live Preview (source: ReText; click image for larger variant)}

• Since release 7.0, it is possible to install ReText on macOS using a pip3 install ReText command.
• It features a live preview, so you see the results of what you're typing while you're typing
• It supports a bunch of dialect and other addons, such as "codelite" for code highlighting
• No fiddling with HTML (except if you wish for), but using Markdown (as used here on SE)
• It can export your texts as HTML, ODT (Open Document Text, i.e. for OpenOffice/LibreOffice), PDF

I use it myself for a while now, and am quite pleased with it: smooth and stable.

Answer 2

You can try MacDown. It works on macOS Sierra, where Mou does not. It's ideal editor for developers, such as technical tutorials, since it supports syntax highlighting (by enabling Syntax highlighted code block in the Rendering Preference pane). Here is the full list of Supported Code Block Syntaxes. The software is open source, free to use and released under MIT License.

Related: Markdown editor for OSX that includes a preview, ideally in real time?

Answer 3

I would suggest using doing your document editing in restructured text, rst, and using a tool such as pandoc to produce the final version(s).

This will allow you to minimise your working files, in a nice version control suitable format while producing output in any or all of: asciidoc, beamer, context, docbook, docx, dzslides, epub, epub3, fb2, html, html5, json, latex, man, markdown, markdown_github, markdown_mmd, markdown_phpextra, markdown_strict, mediawiki, native, odt, opendocument, opml, org, pdf*, plain, revealjs, rst, rtf, s5, slideous, slidy, texinfo, textile.

Answer 4

AsciiDoc

Dr. Matt Neuburg, one of the best technical writers alive, turns out enormous tomes using AsciiDoc (Wikipedia article) and any favorite text editor. AsciiDoc is similar to Markdown, and is semantically equivalent to DocBook XML.

Read his blog post explaining how he works.

AsciiDoc can output to various formats including including HTML, PDF, EPUB, man page.

Answer 5

I use the web app StackEdit to manage blog posts, Gist tutorials and Stack Exchange answers. It is a markdown editor and has this relevant features:

• Works off-line

• Sync with Google Drive and Dropbox, ie, edit on Desktop and Tablet

• Publishing to the following services

  

• Export the formats

  

• Copy the HTML directly from the editor

  

Answer 6

Thanks for the answers. After evaluating both, I chose to use Markdown for writing the lessons, using Mou as a text editor. It does everything I need, is free and then allows me to copy to HTML.