Note: While this post starts with me gushing about AsciiDoc, I do also cover Atom + Markdown, skip down to here to read it.
I am always looking for better tools to make me more productive — whether that’s writing code, writing documentation, or writing books.
Most notably, I have mostly switched to writing everything in Markdown. With one exception: books.
While working with O’Reilly on my Upgrading to PHP 7 ebook (free) I encountered to AsciiDoc. I found it to be a much better solution for writing book-style content than Markdown: it already features syntax for the features added by LeanPub‘s Markua format.
This includes different types of callout boxes (tips, notices, warnings, etc), sidebars, includes, custom attributes, cross references, and more.
My favorite feature is the ability to include portions of external files. This allows me to write syntactically valid PHP files with open tags, that I can then test by passing it to php -l and/or running it (depending on what it does!), but by including specific lines I can omit the opening tag in the final output, or I can bring in specific lines and write about them as I go.
You can also add callout indicators. This works by adding <#> (where # is an integer starting from one), and if you precede it with a comment (e.g. // <1>) it will strip the comment syntax when rendering. You then use the same syntax
For example, given the file code.php:
https://gist.github.com/dshafik/1b0dca4494277cc48b75177af5614703
I can include it, omitting the opening tag, and adding an annotation using:
https://gist.github.com/dshafik/05e68d5c26725aae2872897dc7e52a4a
Now, O’Reilly Atlas, the SaaS tool from O’Reilly for publishing books does some awesome things utilizing AsciiDoc, such as building the final book in multiple formats etc (and I highly recommend checking it out, you can still publish the end result on, say, LeanPub), but most of the features are possible locally using a tool like AsciiDoctor — which is the most popular implementation of AsciiDoc rendering, supporting HTML5, DocBook, ePub, LaTeX, and PDF.
OK, Enough About AsciiDoc, What About Atom?
Alright, so, what about authoring your content? One of the reasons I looked at Atom was that while Markdown has a multitude of available editors, AsciiDoc options are lacking. I started using TextMate with the AsciiDoc bundle, but I wanted live preview, so I switched to PhpStorm with the AsciiDoc plugin, but it didn’t seem to support the full feature set of asciidoctor, and it’s a bit overkill for the task.
After tweeting, I tried AsciiDocFX, but again lacking, specifically support for includes.
For my latest attempt to find authoring nirvana, I’ve moved on to Atom, and what’s what you’re all here for.
Ten 13 Must Have Packages for Markdown and AsciiDoc Authoring in Atom
First the Markdown packages:
3. markdown-writer
markdown-writer adds some conveniences to the authoring of Markdown, such as automatically continuing a list when you hit enter, and support for easier Jekyll authoring.
2. linter-markdown (and linter)
A linter for Markdown syntax
1. markdown-scroll-sync
This one is a must have, it will sync the Markdown preview (Ctrl+Alt+m) scroll position to the current scroll position in the document
Next, the AsciiDoc packages:
asciidoc-assistant
AsciiDoc Assistant is actually a meta-package for four other packages.
4. language-asciidoc
Syntax support and snippets for AsciiDoc (asciidoctor flavor), this is a requirement.
3. autocomplete-asciidoc
Autocomplete for AsciiDoc syntax. I don’t use it much, but it makes some of the more verbose blocks easier to type.
2. asciidoc-preview
An AsciiDoc version of the Markdown preview. Live updating, using and supporting the full range of asciidoctor features, and specifically, it supports includes.
This is as much a necessity as the syntax support.
1. asciidoc-image-helper
When pasting an image into an AsciiDoc document, automatically save it to a specified path and link to it.
Lastly, there are non-markup specific packages that make general writing in Atom much nicer:
4. Zen
A distraction free writing, full-screen writing environment. Hit Cmd+Ctrl+F on OS X, or shift+F11 on Windows and Linux, and it will hide most of the editor UI, including tabs (by default), status bar, file browser, etc.
It will also center your document and can automatically turn on soft wrap (which I recommend).
It works well with both Markdown and AsciiDoc preview panes, and also the Markdown document outline from the markdown-document plugin, and the linter.
I have made one small change to my styles.less to force the status bar to be visible even in Zen mode.
https://gist.github.com/dshafik/cc8effdd008db3f97c5e7a9c2855de77
3. auto-soft-wrap
This addon will simple automatically enable soft wrap based on the file extension. You can add .adoc, .asciidoc, and .md to the settings to make it apply to those files. auto-soft-wrap is not compatible with the Zen plugin, but it’s own soft wrap setting works fine (it always applies though).
2. linter-write-good (and linter)
write-good is a naive linter for English prose, informing you of ways to improve your writing.
linter-write-good brings it into atom UI, using the linter interface it will highlight use of passive voice, words that weaking meaning, and words that was wordy or unnecessary.
For an example of how this can impact your writing, this article was originally written without it, and then re-written following it’s suggestions — you can see the diff with the original article here for comparison.
1. status-stats-jbrains
The last addon is the reason I keep the status bar visible in Zen mode, it shows you your word count, but also the grade level and Flesch-Kincaid Reading Ease scores. This helps to ensure that my writing isn’t unnecessarily complicated.
These plugins are available via the Atom UI, or apm. Hopefully these will improve your Atom authoring experience!