= AsciiDoc Tooling
:experimental:
:url-chrome-extension: https://chrome.google.com/webstore/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia
:url-edge-addon: https://microsoftedge.microsoft.com/addons/detail/asciidoctorjs-live-previ/pefkelkanablhjdekgdahplkccnbdggd
:url-firefox-addon: https://addons.mozilla.org/en/firefox/addon/asciidoctorjs-live-preview
:url-opera-extension: https://addons.opera.com/en/extensions/details/asciidoctorjs-live-preview/
:url-asciidocfx: https://www.asciidocfx.com
:url-asciidocfx-docs: https://www.asciidocfx.com/#truehow-to-install-asciidocfx
:url-eclipse-marketplace: https://marketplace.eclipse.org/content/asciidoctor-editor
:url-eclipse-plugin-github: https://github.com/de-jcup/eclipse-asciidoctor-editor
:url-intellij-plugin-quickstart: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/quick-start.html
:url-intellij-plugin-features: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features.html
:url-scite: https://www.scintilla.org/SciTE.html

Since AsciiDoc syntax is just plain text, you can write an AsciiDoc document using any text editor.
You don't need complex word processing programs like Microsoft Word or Google Docs.
In fact, you shouldn't use these programs because they add cruft to your document that you can't see that makes conversion tedious.

Here's an overview of the different ways to preview and edit your AsciiDoc documents.

== Hosted git repositories

Many popular git repository hosts, including https://github.com/[GitHub], https://about.gitlab.com/[GitLab], and https://codeberg.org/[Codeberg], support editing and previewing AsciiDoc files.
In order to activate this support, the file must have a supported AsciiDoc extension, such as `.adoc`.

When you view an AsciiDoc file on these sites, you will see an HTML preview of the AsciiDoc content.
This preview is powered by Asciidoctor.
The HTML that's rendered is the embedded output produced by the built-in HTML converter.
This means it won't look like a standalone HTML document generated by Asciidoctor.
Rather, the HTML is styled to match the theme of the hosting service and sanitized, so it does not impact the rendering of the page.
This means that certain features may not be available.

GitHub and GitLab apply syntax highlighting to source blocks.
Both services also add floating anchor links next to section titles.
You can deep link to a specific section or to another anchor by adding a fragment identifier to the URL.

The AsciiDoc preview on GitLab currently supports more AsciiDoc features than on GitHub.
On GitLab, you can find support for include directives, admonition icons, diagrams, and STEM expressions.
GitHub, on the other hand, provides a table of contents browser, whereas on GitLab you must add a TOC explicitly using the `toc` attribute.

On GitHub, if you want to see the source of an AsciiDoc file instead of the preview, click the btn:[Code] button or append `?plain=1` to the end of the URL.

If you enter edit mode by clicking the btn:[Edit file] button on either GitHub or GitLab, you can modify the source of the AsciiDoc file and see a preview of the modified source before you commit your changes.
GitLab even allows you to edit multiple files in a single commit using its Web IDE.

== Web browser add-ons (preview only)

To preview an AsciiDoc document in a web browser, install the {url-chrome-extension}[Chrome extension^], the {url-edge-addon}[Edge add-on^], the {url-firefox-addon}[Firefox add-on^], or the {url-opera-extension}[Opera extension^] (all produced from the same code base).
Then you can see the AsciiDoc file rendered as HTML just by visiting it.

== IDEs and text editors

The following IDEs and text editors support the AsciiDoc syntax and most provide document preview rendering with Asciidoctor.

=== AsciiDocFX

{url-asciidocfx}[AsciiDoc FX^] is an editor and terminal emulator written with JavaFX 8.
See its documentation for {url-asciidocfx-docs}[download and installation instructions^].

=== Atom

[IMPORTANT]
====
The Atom editor's official site has announced that Atom is being sunset at the end of 2022.

See https://github.blog/2022-06-08-sunsetting-atom/[Sunsetting Atom]
====

Install https://atom.io/[Atom^].
Then from the Atom editor menus, navigate to menu:Atom[Preferences].
From there, open the menu:Packages[] tab and install:

https://atom.io/packages/asciidoc-preview[AsciiDoc Preview^] :: enables live preview
https://atom.io/packages/language-asciidoc[AsciiDoc Language^] :: enables syntax highlighting (AsciiDoc language support)
https://atom.io/packages/asciidoc-image-helper[AsciiDoc Image Helper^] :: provides the ability to paste images from the clipboard
https://atom.io/packages/autocomplete-asciidoc[AsciiDoc Autocomplete^] :: automatically completes AsciiDoc language items
https://atom.io/packages/asciidoc-assistant[AsciiDoc Assistant^] :: Installs useful components to Atom for editing AsciiDoc files (including the above packages)

=== Brackets

Install http://brackets.io/[Brackets^].
Then from the Brackets file menu, open the extension manager.
Browse available extensions and install `AsciiDoc Preview`.

More information:

* https://github.com/asciidoctor/brackets-asciidoc-preview[AsciiDoc Preview for Brackets^]

=== Eclipse

Install the open source plugin `Asciidoctor Editor` from the {url-eclipse-marketplace}[Eclipse Marketplace^] or visit the
{url-eclipse-plugin-github}[project repository^].

=== IntelliJ IDEA

The community AsciiDoc plugin adds support to edit AsciiDoc files in the IDE with syntax highlighting, auto-completion and a live preview.
It includes support for Antora and Spring REST Docs and creates PDFs using Asciidoctor PDF.

It works with the free community editions as well as with the paid editions of IntelliJ IDEA, CLion, PhpStorm, RubyMine, Android Studio etc.

{url-intellij-plugin-quickstart}[Install the AsciiDoc plugin^] or {url-intellij-plugin-features}[learn more about its features^].

=== SciTE

Install {url-scite}[SciTE^] 5.2.3 or later.
To enable the AsciiDoc lexer, follow these steps:

. Edit the user properties file and remove `asciidoc` from the list in `imports.exclude`.
. Restart SciTE.
. SciTE will automatically apply AsciiDoc syntax highlighting to files ending in `.adoc` and `.asciidoc`.

SciTE does not provide document preview rendering like other editors listed on this page.

=== Visual Studio Code

Visual Studio Code provides rich language support for AsciiDoc and a live preview as you type.

. Install https://code.visualstudio.com/[Visual Studio Code^].
. Launch Visual Studio Code and open the Quick Open dialog by pressing kbd:[Ctrl,P].
. Type the following command to locate and install the AsciiDoc extension (by João Pinto):
+
 ext install asciidoctor.asciidoctor-vscode

More information:

* https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode[AsciiDoc extension for Visual Studio Code^]
