These instructions are for people who have not used AsciiDoc markup before.
All of the information in this help file comes directly from:
Asciidoctor is the processor and publishing toolchain for converting AsciiDoc files to HTML, PDF and other formats. AsciiDoc is the markup syntax.
AsciiDoc is a lightweight markup language built around the idea that authors should spend their time writing, not messing around with finicky formatting issues. When you have to worry about inconsistent formatting that constantly creeps into what-you-see-is-what-you-get (WYSIWYG) editors like Microsoft Word or OpenDocs, writing becomes frustrating and more time consuming than it should be. Simply put, writing in plain text takes some of the frustration out of writing by creating consistent formats. One linespace will always be just one linespace. Also, plain text can easily be translated to different outputs (HTML, HTML5, PDF, etc.) for different applications.
AsciiDoc is two things:
A mature, plain-text writing format for authoring notes, articles, documentation, books, ebooks, web pages, slide decks, blog posts, man pages and more.
A text processor and toolchain for translating AsciiDoc documents into various formats (called backends), including HTML, DocBook, PDF and ePub.
Do not!
Unless you work in Ruby, like diving into the guts of your operating system, and want to compile a backend on your computer, there is no need for you to install the Asciidoctor toolchain. The AsciidocFX, Atom, and Brackets text editors/IDEs work well for editing and previewing the convention documents.
|
💡
|
If you use Windows 10 and you want to install the Asciidoctor toolchain, initiate the Windows Subsystem for Linux (WSL) and install Ruby, Ruby Version Manager, and the Asciidoctor toolchain there. The A quick workflow for experienced Git and GitHub users document will get you started. |
If you have not used AsciiDoc markup before, it’s a good idea to open thep AsciiDoc Writer’s Guide' and read through it with one of the .adoc files open in your text editor/IDE. Honestly, the AsciiDoc Writer’s guide is well done.
Some of the formatting used in the WGFAST conventions:
-
Attributes (globally set in the document header, but can be modified inline)
-
Section titles (heading, including the document title)
-
Lists
-
Breaks
-
Formatted text
-
Tables
-
Included files
|
💡
|
You can find a list of AsciiDoc Attributes and their descriptsions in Appendix A: Catalog of Documents Attributes of the Asciidoctor User Manual. |
Below we will show some of the basics of the document header with its attributes, section titles, formatted text, breaks, and lists. Please refer to the online documentation for detailed explanations of other AsciiDoc markup.
The document’s title, authors, and attributes are set in the header.
= A metadata convention for processed acoustic data from active acoustic systems # (1) ICES WGFAST Topic Group, TG-AcMeta # (2) :revnumber: 1.10 --------- :revdate: 1 November 2016 | :toc: left | :toclevels: 3 | :doctype: book | :xrefstyle: short | :source-highlighter: highlightjs | --- # (3) :highlightjsdir: highlight | :sectnumslevels: 4 | :stem: latexmath | :eqnums: | :bibtex-file: references.bib | :bibtex-style: ices-journal-of-marine-science ---------
-
The title, indicated by a single
=. -
The second line of the document lists the author(s).
-
Attributes and their settings.
-
Revision number:
:revnumber: 1.10 -
Revision date:
:revdate: 1 November 2016 -
Position of the Table of Contents:
:toc: left -
Levels of the TOC to show:
:toclevels: 3 -
Document type:
doctype: book -
Reference style:
:xrefstyle: short -
Syntax highlighter:
:source-highlighter: highlightjs -
Location of the highlight.js source code:
:highlightjsdir: highlight -
Set the number of section levels:
:sectnumslevels: 4 -
Mathematical processor:
:stem: latexmath -
Control equation numbering:
:eqnums: -
Bibliography file:
:bibtex-file: references.bib -
Citation and bibliography style
:bibtex-style: ices-journal-of-marine-science
= Document Title (Level 0) == Section Level 1 === Section Level 2 ==== Section Level 3 ===== Section Level 4 ====== Section Level 5 = Section Level 0
bold *constrained* & **un**constrained italic _constrained_ & __un__constrained bold italic *_constrained_* & **__un__**constrained monospace `constrained` & ``un``constrained monospace bold `*constrained*` & ``**un**``constrained monospace italic `_constrained_` & ``__un__``constrained monospace bold italic `*_constrained_*` & ``**__un__**``constrained
bold constrained & unconstrained
italic constrained & unconstrained
bold italic constrained & unconstrained
monospace constrained & unconstrained
monospace bold constrained & unconstrained
monospace italic constrained & unconstrained
monospace bold italic constrained & unconstrained
The yellow banana slug, + rustled through the leaves until a + ravenous raccoon appeared. [%hardbreaks] Ruby is red. Python is green. Java is black.
The yellow banana slug
rustled through the leaves until a
ravenous raccoon appeared.
Ruby is red.
Python is green.
Java is black.
before ''' after
before
after
<<<
* Snoopy * Garfield * Brian Griffin
-
Snoopy
-
Garfield
-
Brian Griffin
* level 1 ** level 2 *** level 3 **** level 4 ***** level 5 * level 1
-
level 1
-
level 2
-
level 3
-
level 4
-
level 5
-
-
-
-
-
level 1
. Wake up . Make coffee . Drink coffee
-
Wake up
-
Make coffee
-
Drink coffee
. Wake up . Make coffee .. Put medium ground coffee in French press .. Pour boiling water into French press .. Steep until desired strength . Drink coffee
-
Wake up
-
Make coffee
-
Put medium ground coffee in French press
-
Pour boiling water into French press
-
Steep until desired strength
-
-
Drink coffee
Markdown is probably more familiar to many people, especially if you work in R and use RMarkdown. So, why are we using AsciiDoc instead of Markdown? Many or the formatting options in Markdown are the same or similar in AsciiDoc, but AsciiDoc syntax is more concise and it is more flexible when creating table of contents, lists, tables, and admonitions (tip, notes, warnings, etc.).
The table comparing AsciiDoc and Markdown syntax in this section was recreated from the 1.5.3 Comparison by example section of the Asciidoctor User Manual.
The following table shows the AsciiDoc syntax as it compares to Markdown. Since AsciiDoc supports a broader range of syntax than Markdown, this side-by-side comparison focuses mainly on areas where the syntax overlaps.
| Language Feature | Markdown | AsciiDoc |
|---|---|---|
Bold (constrained) |
**bold** |
*bold* |
Bold (unconstrained) |
**b**old |
**b**old |
Italic (constrained) |
*italic* |
_italic_ |
Italic (unconstrained) |
n/a |
__i__talic |
Monospace (constrained) |
`monospace` |
`monospace` |
Monospace (unconstrained) |
`m`onospace |
``m``onospace |
Link with label |
[AsciiDoc](http://asciidoc.org) |
http://asciidoc.org[AsciiDoc] |
Relative link |
[user guide](user-guide.html) |
link:user-guide.html[user guide]
xref:user-guide.adoc[user guide] |
File link |
[get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/mydoc.pdf) |
link:{site-url}/assets/mydoc.pdf[get the PDF] |
Cross reference |
See link:#_usage[Usage].
<h2 id="_usage">Usage</h2> |
See <<_usage>>.
== Usage |
Block ID / anchor |
<h2 id="usage">Usage</h2> |
[#usage]
== Usage |
Inline anchor |
n/a |
. [[step-1]]Download the software |
Inline image w/ alt text |
 |
image:logo.png[Logo] |
Block image w/ alt text |
n/a |
image::logo.png[Logo] |
Section heading* |
## Heading 2 |
== Heading 2 |
Blockquote* |
> Quoted text.
>
> Another paragraph in quote. |
____
Quoted text.
Another paragraph in quote.
____ |
Literal block |
$ gem install asciidoctor |
Indented (by 1 or more spaces)
$ gem install asciidoctorDelimited
....
$ gem install asciidoctor
.... |
Code block* |
```java
public class Person {
private String name;
public Person(String name) {
this.name = name;
}
}
``` |
[source,java]
----
public class Person {
private String name;
public Person(String name) {
this.name = name;
}
}
---- |
Unordered list |
* apples
* orange
* temple
* navel
* bananas |
* apples
* oranges
** temple
** navel
* bananas |
Ordered list |
1. first
2. second
3. third |
. first
. second
. third |
Thematic break (aka horizontal rule)* |
***
* * *
---
- - -
___
_ _ _ |
''' |
Typographic quotes (aka “smart quotes”) |
Enabled through an extension switch, but offer little control in how they are applied. |
The `'90s popularized a new form of music known as "`grunge`" rock.
Its influence extended well beyond music. |
Document header |
Slapped on as “front matter”
---
layout: docs
title: Writing posts
prev_section: defining-frontmatter
next_section: creating-pages
permalink: /docs/writing-posts/
--- |
Native support!
= Writing posts
:awestruct-layout: base
:showtitle:
:prev_section: defining-frontmatter
:next_section: creating-pages |
Admonitions |
n/a |
TIP: You can add line numbers to source listings by adding the word `numbered` in the attribute list after the language name. |
Sidebars |
n/a |
.Lightweight Markup
****
Writing languages that let you type less and express more.
**** |
Block titles |
n/a |
.Grocery list
* Milk
* Eggs
* Bread |
Includes |
n/a |
include::intro.adoc[] |
URI reference |
Go [Home][home].
[home]: https://example.org |
:home: https://example.org
Go {home}[Home]. |
Custom CSS classes |
n/a |
[.path]_Gemfile_ |
* Asciidoctor also supports the Markdown syntax for this language feature.
You can see that AsciiDoc has the following advantages over Markdown:
-
AsciiDoc uses the same number of markup characters or less when compared to Markdown in nearly all cases.
-
AsciiDoc uses a consistent formatting scheme (i.e., it has consistent patterns).
-
AsciiDoc can handle all permutations of nested inline (and block) formatting, whereas Markdown often falls down.
-
AsciiDoc handles cases that Markdown doesn’t, such as a proper approach to inner-word markup, source code blocks and block-level images.