These instructions are to help contributors install and use either AsciidocFX, Atom, or Brackets to edit the WGFAST convention documents.
There are three ways you can view and edit AsciiDoc documents.
-
Install the Asciidoctor toolchain and all its dependencies to create backends (PDF, HTML, ePubs, Word docs, etc.). Requires Ruby. You cannot see updates as you edit.
-
Install AsciiDoc browser extensions in Chrome, Firefox, or Opera and open files in your browser. Preview only. To see live updates you will have to install and set up a system monitor to watch for file changes.
-
Use a modern text editor/IDE that supports live preview and syntax highlighting of AsciiDoc documents. Syntax highlighting helps differentiate between markup commands and text.
Answer: Installing and using a modern text editor/IDE is the easiest option to edit and preview AsciiDoc documents across multiple platforms!
|
💡
|
IDE = Integrated Development Environment |
|
🔥
|
This document is not going to give you all the tips and tricks for each editor/IDE. It is only meant to help you choose an editor/IDE and to get started. Please refer to the manuals and online community help sections for in depth information on each program. |
AsciidocFX is supported on macOS, Windows, and Linux.
The easiest way to install AsciidocFX is to go to the installation section of the AsciidocFX website, download the installer for your system, and run it.
There is no Git/GitHub GUI native to AsciidocFX, but there is a terminal emulator. This means that while working in AsciidocFX, you can open the terminal emulator and run Git commands. The terminal emulator will open in your current working directory.
To change what terminal is used, update the settings in the Settings → Terminal Settings tab (left side of the screen).
|
💡
|
Windows users, you might want to change the path from the Window’s command prompt to the path for Git Bash. The path to Git Bash will depend on where you installed Git. The path to Git Bash under a default installation would be: C:\Program Files\Git\bin\bash.exe
|
Atom is supported on macOS, Windows, and Linux.
To install Atom, click the big, yellow "Download" button at Atom.io and run the installer. If the operating system listed above the download button is not your operating system, you can find other builds and releases at https://github.com/atom/atom (scroll down).
To preview AsciiDoc and Markdown documents you will have to install a few packages.
From the Welcome Page you can click on Install a Package or go to File → Settings and click on Install at the bottom of the list of options.
-
asciidoc-assistant
Installs the following packages:-
asciidoc-image-helper
Provides the ability to past images from the clipboard. -
asciidoc-preview
Shows an HTML preview for the AsciiDoc content in the current editor. -
autocomplete-asciidoc
AsciiDoc language autocompletions. -
language-asciidoc
Syntax highlighting and snippets for AsciiDoc.
-
-
Other packages you might want
-
markdown-preview-plus
To show an HTML preview of Markdown (.md) documents. -
atom-terminal
Opens an external terminal in the current directory. -
terminal-tab Opens a terminal pane within Atom in the current directory.
-
You do not need both atom-terminal and terminal-tab. One or the other will do.
|
ℹ️
|
If asciidoc-assistant failed to install any of its dependencies, you will have to install those package separately. |
-
Ctrl+Shift+P(Linux/Windows) orcmd+shift+P(macOS). Opens the Command Pallet where you can find and run available commands. -
Ctrl+Shift+A(Linux/Windows) orcmd+shift+A(macOS). Opens AsciiDoc live preview. -
Ctrl+Shift+M(Linux/Windows) orcmd+shift+M(macOS). Opens Markdown live preview.
Atom is a little friendlier in that it opens to a "Welcome Page" with links to help get you started. You can turn this option off by un-checking the box next to "Show Welcome Guide when opening Atom".
Atom comes bundled with a GUI for Git and GitHub. You have to supply your GitHub login credentials the first time you push commits to GitHub with the GUI.
To work in a terminal, you have to install an external package. There are a number of Atom packages that give you access to a terminal. The simplest is atom-terminal which opens your external terminal in the root directly of the project. terminal-tab opens a terminal within Atom that you can dock in different places, but the package can be a little flaky - closing the terminal by clicking the x to close the tab instead of exiting out of the terminal (typing exit at the command line) crashes Atom.
Instructions for working with Git in a terminal are in the Suggested workflow to contribute to the ICES WGFAST convention documents file.
-
Open the settings of the terminal package you installed and make sure the path to your terminal is correct.
-
Open the terminal when you need to stage, commit, and push to GitHub.
Please see How to use Git/GitHub GUI in Atom
Brackets is supported on macOS, Windows, and Linux
To install Brackets, click the big, blue "Download Brackets 1.14.1" button at Brackets.io and run the installer. If the correct installer for your operating system does come up, you can find other builds and releases at https://github.com/adobe/brackets (scroll down).
To preview AsciiDoc and Markup documents and to interface with Git/GitHub, you have to install a few extensions using the Extension Manager.
Go to File → Extension Manager or click on the Extension Manager button on the right.
-
AsciiDoc Preview
Live preview of AsciiDoc documents. -
Markdown Preview
Live preview of Markdown documents. -
Brackets-Git
Integration of Git into Brackets. -
Alice - Spell Checking
Adds offline spell checking capabilities to Brackets. -
Alice Dictionaries
Provides dictionary data for the Alice spell checker.
-
To enable the AsciiDoc or Markdown preview and Git extensions you have to select the respective icons on the right. The AsciiDoc and Markdown preview icons will only be available if an
.adocor.mdfile is open. -
The AsciiDoc live preview pane can be float if you do not like its default location on the bottom of the screen.
-
There are four icons in the top-right of the AsciiDoc preview pane:
-
synchronization icon
-
If auto-sync to the editing location is turned off, pressing this button will scroll the preview to the cursor’s location in the source pane.
-
-
export to browser icon
-
Exports the current preview to your browser. Live update is not available when the preview is in your browser.
-
-
settings icon
-
Auto-sync the preview to the source pane in the
Updatetable and turn on math rendering in theViewtab.
-
-
dock/undock icon
-
Docs the preview pane at the bottom of the screen or undocks it.
-
-
For more on the available features of of each extension, please visit their websites:
After installing the Brackets-Git extension, you can clone, branch, stage, commit, and push to your remote repository by using Git commands in a terminal or you can use the GUI.
-
First make sure the path your terminal is correct. Go to
File → Git Settings… → Git Configuration. -
Click on the Git icon on the right side, then click on the terminal icon in the Git pane to open your terminal.
Instructions for working with Git in a terminal are in the Suggested workflow to contribute to the ICES WGFAST convention documents file.
Please see How to use Git/GitHub GUI in Brackets
Various parts of the "How-to" documents were written using the three text editors/IDEs on a Dell XPS 15 (9560) with Microsoft Windows 10 Pro Build 18363, 32 GB RAM.
If anyone wants to update this section for macOS and Linux, please do!
| AsciidocFX | Atom | Brackets | |
|---|---|---|---|
Pros |
|
|
|
Cons |
|
|
|
Quirks |
|
|
|