{"id":66477,"date":"2022-08-15T09:01:42","date_gmt":"2022-08-15T09:01:42","guid":{"rendered":"https:\/\/www.cryptocabaret.com\/?p=66477"},"modified":"2022-08-15T09:01:42","modified_gmt":"2022-08-15T09:01:42","slug":"try-asciidoc-instead-of-markdown","status":"publish","type":"post","link":"https:\/\/www.cryptocabaret.com\/?p=66477","title":{"rendered":"Try Asciidoc instead of Markdown"},"content":{"rendered":"

Try Asciidoc instead of Markdown<\/span>
\nSeth Kenlon<\/a><\/span>
\nMon, 08\/15\/2022 – 03:00<\/span><\/p>\n

\n
1 reader likes this<\/div>\n
1 reader likes this<\/div>\n<\/div>\n
\n

I’m a happy user of the XML-based Docbook<\/a> markup language. To me, it’s a precise, explicit, and detailed system that allows me to have contextual and domain-specific metadata in what I write. Best of all, though, it can be transformed (that’s what XML users call it when XML is converted into another format) into nearly any format, including HTML, EPUB, FO for PDF, plain text, and more. With great power comes a lot of typing, though, and sometimes Docbook feels like it’s surplus to requirements. Luckily, there’s Asciidoc<\/a>, a system of writing plain text with the same markup-less feel of Markdown, but that transforms to Docbook to take advantage of its precision and flexibility.<\/p>\n

Asciidoc rules<\/h2>\n

Like Markdown, one of the goals of Asciidoc is that you don’t really have to learn<\/em> it. Instead, it aims to be intuitive and natural. You may well have written snippets of valid Asciidoc without realizing it if you’ve ever added a little style to a plain text document for readability. For instance, if you habitually separate paragraphs with a blank line, then you’ve written the equivalent of the HTML <\/p>\n

<\/code> or Docbook <\/para><\/code> tag. It seems obvious, and yet in academia separating paragraphs with blank lines isn’t generally done, so even this simple convention is technically markup.<\/p>\n

Here’s the most common syntax.<\/p>\n<\/p>\n

\n
More Linux resources<\/div>\n
\n
Linux commands cheat sheet<\/a><\/div>\n
Advanced Linux commands cheat sheet<\/a><\/div>\n
Free online course: RHEL technical overview<\/a><\/div>\n
Linux networking cheat sheet<\/a><\/div>\n
SELinux cheat sheet<\/a><\/div>\n
Linux common commands cheat sheet<\/a><\/div>\n
What are Linux containers?<\/a><\/div>\n
Our latest Linux articles<\/a><\/div>\n<\/p><\/div>\n<\/p><\/div>\n

Text styles<\/h3>\n

Text styles include the basics such as bold, italics, and code font. Most of the notation is relatively intuitive, with the possible exception of italics.<\/p>\n

*Bold*<\/strong><\/p>\n

_Italics_<\/em><\/p>\n

*_Bold and italic_*<\/strong><\/em><\/p>\n

`Monospace or code`<\/code><\/p>\n

Code<\/h3>\n

Code is marked with backticks or by explicit declaration of a code block.<\/p>\n

`Monospace or code`<\/code><\/p>\n

\n
[source,python]
\n----
\nprint('a whole code block')
\n----<\/div><\/div><\/pre>\n
Headlines<\/h3>\n
Headings are marked with leading equal signs (=<\/code>):<\/p>\n
= Heading 1 (<\/p>\n
<\/h1>\n
<\/code>)<\/p>\n
== Heading 2 (<\/p>\n
<\/h2>\n
<\/code>)<\/p>\n
=== Heading 3 (<\/p>\n
<\/h3>\n
<\/code>)<\/p>\n
==== Heading 4 (<\/p>\n
<\/h4>\n
<\/code>)<\/p>\n
===== Heading 5 (<\/p>\n
<\/h5>\n
<\/code>)<\/p>\n
====== Heading 6 (<\/p>\n
<\/h6>\n
<\/code>)<\/p>\n
Links<\/h3>\n
Hyperlinks favor the link first, followed by the word or phrase used to “disguise” the link as text.<\/p>\n
This is a http:\/\/example.com[hyperlink<\/a>] that leads to the example.com site.<\/p>\n
I don’t find this as elegant as Markdown’s link notation, but then it’s a lot more flexible. For instance, you can add attributes in Asciidoc links:<\/p>\n
This is a https:\/\/example.com[link,role=external,window=_blank<\/a>] with the target=\"_blank\"<\/code> attribute set.<\/p>\n
Lots more<\/h3>\n
Asciidoc also features internal links so you can link from one section to another, a standard for document headers, automatic table of content generation, the ability to include other documents within another, and much much more.<\/p>\n
But best of all, Asciidoc is actually standardized<\/em>. Not everyone knows it, but the term “Markdown” doesn’t refer to one markup-light language. Different organizations and groups regularly customize and alter Markdown for their own use, so when you use Markdown you really ought to verify which<\/em> markdown you’re meant to use. Many of the conventions you might have learned from one website using Markdown don’t carry over to another site using Markdown. There’s essentially no standard for Markdown, and that’s resulted in such confusion that the Commonmark.org<\/a> project has been formed in an attempt to assemble a standardized definition.<\/p>\n
Asciidoc was designed from the start with a standard definition, so the tool or website that claims to parse Asciidoc actually does parse all valid Asciidoc, because there’s only one valid Asciidoc.<\/p>\n
Asciidoc to anything<\/h2>\n
The point of writing in a markup-light language like Asciidoc is to ensure predictability and consistency when text is parsed. You want a person to write a script, or to run an application someone else has written, to be able to transform your plain text into whatever format works best for them. Sometimes that’s HTML (incidentally Markdown’s native output format, and fallback language when there’s something missing from its own syntax.) Other times it’s an EPUB, or a PDF for printing, Docbook, a LibreOffice document, or any number of possible output formats.<\/p>\n
There are several tools to help you transform Asciidoc to another format. A popular command is Asciidoctor<\/a>, which you can install using your package manager. For instance, on Fedora, CentOS, or RHEL:<\/p>\n
\n$ <\/span>sudo<\/span> dnf install<\/span> asciidoctor<\/code><\/span><\/pre>\n
On Debian-based systems:<\/p>\n
\n$ <\/span>sudo<\/span> apt install<\/span> asciidoctor<\/code><\/span><\/pre>\n
Alternately, you can install it on any OS with Ruby:<\/p>\n
\n$ <\/span>gem install<\/span> asciidoctor<\/code><\/span><\/pre>\n
Here’s a simple example of an Asciidoc document, which you can create using any text editor<\/a> or even a word processor (like LibreOffice<\/a>) as long as you save the file as plain text. Most applications expect a plain text document to use the extension .txt<\/code>, and while it’s a convention use the extension .adoc<\/code> for Asciidoc, it’s not necessary. Asciidoctor doesn’t require any special extension.<\/p>\n
\n
= This is my example document

\nIt's not written in _Markdown_, nor _reStructured Text_.
\nThis is *Asciidoc*.

\nIt can be transformed into nearly any format using the tool `Asciidoctor` and other similar parsers.
\nTry it for yourself!<\/span><\/div><\/div><\/pre>\n
To transform an Asciidoc document to HTML, run asciidoctor<\/code>:<\/p>\n
\n$ <\/span>asciidoctor example.adoc<\/code><\/span><\/pre>\n
The file example.adoc<\/code> is transformed into HTML5 by default, but you can use different backends to gain access to more formats.<\/p>\n
From Asciidoc to XML<\/h2>\n
My favourite is the Docbook backend, because it transforms my Asciidoc to Docbook XML, allowing me to use my existing Docbook toolchain (custom Makefiles, Apache FOP, xsltproc<\/code>, xmlto<\/code>, and so on) to complete my work:<\/p>\n
\n$ <\/span>asciidoctor --backend<\/span> docbook5 example.adoc<\/code><\/span><\/pre>\n
This outputs Docbook XML. The final two built-in backends are xhtml5<\/code> and manpage<\/code>.<\/p>\n
From Asciidoc to EPUB<\/h2>\n
If you want to turn your writing into an ebook, you can install the EPUB3 backend:<\/p>\n
\n$ <\/span>gem install<\/span> asciidoctor-epub3<\/code><\/span><\/pre>\n
Transform your Asciidoc into EPUB:<\/p>\n
\n$ <\/span>asciidoctor-epub3 example.adoc<\/code><\/span><\/pre>\n
From Asciidoc to PDF<\/h2>\n
You can transform Asciidoc directly to PDF, too:<\/p>\n
\n
$ gem install<\/span> asciidoctor-pdf
\n$ asciidoctor-pdf example.adoc<\/div><\/div><\/pre>\n
\n
  \"Asciidoctor-pdf\"<\/div>\n
Image by: <\/span><\/p>\n
(Seth Kenlon, CC BY-SA 4.0)<\/p>\n<\/div>\n<\/article>\n
Who should use Asciidoc<\/h2>\n
Asciidoc is excellent for technical writers and writers who have precise requirements for how they want text to be organized and parsed. It’s a clear and strictly defined markup format that eliminates the confusion of competing Markdown formats, and it transforms to all the major formats. Asciidoc is admittedly more verbose and possibly less intuitive than Markdown, but it’s still just plain text so you can author on anything, and Asciidoctor makes processing easy. Next time you write a document for any purpose, consider trying Asciidoc.<\/p>\n<\/div>\n
\n
Next time you write, use Asciidoc and Asciidoctor as alternatives to Markdown.<\/p>\n<\/div>\n
\n
\n
  \"Person<\/div>\n<\/article>\n<\/div>\n
\n
Linux<\/a><\/div>\n
Documentation<\/a><\/div>\n<\/p><\/div>\n
What to read next<\/div>\n
\n
Markdown beginner’s cheat sheet<\/a><\/div>\n<\/p><\/div>\n

\n        \"Creative<\/a>This work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.<\/div>\n
\n
\n
Register<\/a> or Login<\/a> to post a comment.<\/div>\n<\/p><\/div>\n<\/section>\n
Powered by WPeMatico<\/a><\/small><\/p>\n","protected":false},"excerpt":{"rendered":"
Try Asciidoc instead of Markdown Seth Kenlon Mon, 08\/15\/2022 – 03:00 1 reader likes this 1 reader likes this I’m a happy user of the XML-based Docbook markup language. To me, it’s a precise, explicit, and detailed system that allows me to have contextual and domain-specific metadata in what I write. Best of all, though, […]<\/p>\n","protected":false},"author":1,"featured_media":66478,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[307],"tags":[],"class_list":["post-66477","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-open-source"],"_links":{"self":[{"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/posts\/66477","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=66477"}],"version-history":[{"count":0,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/posts\/66477\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/media\/66478"}],"wp:attachment":[{"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=66477"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=66477"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=66477"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}