Sublime Forum

Support (status) for Asciidoc(tor)



I’m aware that lot of people jumped to vscode editor since it provides good support for many languages. Personally, I’m not thrilled to use Electron app as editor and would like something better/easier to configure that Emacs/Vim (I use VIm for certain simpler things) and that’s why I bought ST3 license long-ago.

Anticipating my future needs, I might do some light PHP coding and possibly some Python development, but I do foresee lot of writing using Asciidoc(tor) markup as well as some Markdown (which is supported well in ST), so wonder about the future of Asciidoc-related packages for ST(4)?

Currently there are two:

  1. Asciidoctor which is abandoned having last commit in 2015 and

  2. AsciiDoc having last commit from June 2018, seemingly embraced by ST team, although in PackageControl it is stated: " Currently looking for a maintainer!" and on Github it is still stated: "AsciiDoc Package for Sublime Text2 " :thinking:

So, the question is whether one can consider that ST(4) is reliable editor for those having the need to write Asciidoc(tor) markup extensively?

The situation with both Emacs & Vim is also not thrilling…only vscode seems to enjoy some active support via this extension and in that case my option would be to count on Onivim2 which is supposed to enable one to take advantage of vscode extension’s ecosystem.




Considering the AsciiDoc package only contains syntax highlighting, snippets and settings. It should work fine in newer versions of ST.



Hi @gour, I’m facing the same problems as you, since I also work with AsciiDoc (Ruby) on a daily base. None of the available AsciiDoc syntaxes work well, and they often break up when encountering patterns that they can’t handle, which ultimately breaks up most of the functionality that’s supposed to be available on a document.

The problem is not really related to any specific editor, but to the fact that the AsciiDoc syntax is very hard to handle with RegEx-based syntax definitions. To get a decent support for AsciiDoc, you’ll have to either look for a dedicated editor (e.g. Asciidoc FX or for an AsciiDoc Language Server — i.e. a syntax based on the Language Server Protocol (LSP).

Language Servers are real parsers created ad hoc for a syntax, so they are able to offer full support for any language or markup syntax, since they are not constrained by the limits of a RegEx based syntax definition. Also, Language Servers are editor/IDE agnostic applications that will work on any editor that supports LSP (ST3 does have an LSP package).

The problem is that no one has created an AsciiDoc Language Server so far — at least, none that I know of.




let me share how I did solve my problem…

For most of the (simple) content that I write I decide to use Markdown markup, while for the content which requires higher quality output I decided to use ConTeXt. for a long time I was considering which markup to use, but I was convinced when I got reply from Hans Hagen - main developer behind ConTeXt who wrote on the context list:

and he is right…to take full advantage of AsciiDoc(tor) one has to write markup which is not so simple any longer, but in that situation ConTeXt provides better typesetting engine for final output than anything available for AsciiDoc. Moreover, ConTeXt can also typeset Markdown documents. :wink:



Thanks for sharing @gour!

My solution has been to edit the AsciiDoc ST package and start to tweak it to prevent braking the syntax.

Today I’ve finally pushed to GitHub my initial draft:

I’ve ported the syntax from the old ST2 format to the new ST3 format, after having applied some of the patches in the pending pull requests of the upstream repository.

Since I need it to work every day, my approach has been to remove from the syntax definition those elements that tend to break up the document, and then gradually start to reimplement them again without the original problem. In this respect, “less is more” — i.e. I’d rather have less syntax elements covered, but prevent the document from breaking up.

Unfortunately, the repository is not yet usable as a package (the current work is not even on master), I’ll need to remove some spurious files and setup the package settings to allow third parties to clone it in the ST packages folder, so that it will automatically update via Git. Since right now I’m the only one using it, I’m in no hurry to make it a full fledged package, but of course if others ask me to, I’ll happily accelerate the procedure (having others use the package would provide more feedback, which should help isolate the problematic elements even further).



@tajmone . I’m a heavy user of AsciiDoc (in its asciidoctor implementation) and have so far been writing exclusively in sublime. I do appreciate sublime for many reasons, and its AsciiDoc support has been almost good enough for me. In 2017 i submitted this PR against the original GitHub project, and although it was never merged, i’ve used that patched package ever since. I see that your fork/branch ( incorporates an equivalent fix (and probably much more), and so i’d be happy to switch over to using your package.

Please let me know how you want me to proceed switching to your package. For example, if you want to apply additional tidying-up or documentation before i make the switch, then please do that and give me a shout when it’s ready.




indeed I’ve applied to my repo a couple of fixes from the PRs that were never merged on the upstream repository. One of them was by user @bsmith-n4, which I duly credit in my integration commit:

the other one, I don’t remember where I took it from, which is why I haven’t yet merged to master my fork work — i.e. I’ve already updated the REAME file, but I still need to add in the credits the authors from the upstream PRs whose fixes I’ve integrated. So, I only need to go through all the commits history and find the fixes (I think they were 2, maximum 3, which I picked out from the PRs, to integrate them in the old ST3 TextMate syntax, before migrating to the .sublime-syntax format).

Once I’ve added the due credits in the README, I’m ready to merge into master (I’m fussy about crediting where credit it’s due). Then it should be possible to install the package locally via Git, directly in ST3’s Packages/ folder.

I’m really glad to hear that someone else will be benefiting from the package, which means I’ll also get some feedback on how to improve it, and contributions might flow in in the course of time.

In the weekend I’ll finish polishing the README, add the missing credits and some instructions on how to install it via Git, and then I can merge into master, since the package is already usable (and I do use it every day). When it’s done, I’ll confirm it to you here in this post, and from then on the repository Issues can be used to freely discuss any improvements suggestions, a roadmap, etc.



sounds perfect @tajmone: looking forward to it



@GeraldLoeffler, I’ve update the Credits section and merged to master:

I think the best way to install it is by forking and then cloning it via Git into ST3 “Packages” data folder, so it won’t be in a packed archive format and you can also edit it to create PRs, etc. My understanding is that the package will be auto-updated if I add new commits to master, which I only do when a fix has been tested thoroughly enough on the dev branches first.



ok, @tajmone, i’m up-and-running with your “package”. Specifically, i’ve done (on my Mac)

cd /Users/gerald/Library/Application\ Support/Sublime\ Text\ 3/Packages
git clone

restarted sublime, then ST3-Asciidoctor shows up in sublime’s Package Control: List Packages and AsciiDoc syntax is seemingly correctly highlighted. So all is good.

I’ve seen the GitHub Issues you’ve created in your repo, and will do likewise if i find anything worth improving.

Thank you!



Glad to hear that!

Great. I’ll also buzz you via repo Issues to consult you when there are major decisions to be taken the, so we’re both happy about how it will affect daily usage.

Didn’t you experience problems for omitting the subfolder name Asciidoctor after the command?