asciidoctor / asciidoctor.org

:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.

Asciidoctor Project Site

❗

Are you looking for the Asciidoctor documentation or AsciiDoc Language documentation? They’ve moved! You can view the published documentation at https://docs.asciidoctor.org. To submit an issue or pull request to the Asciidoctor or AsciiDoc documentation, see the Asciidoctor repository or AsciiDoc Language repository, respectively.

This is the project site for the Asciidoctor project. The site is composed in AsciiDoc, styled by Foundation 4, baked with Awestruct, and hosted on Netlify.

For instructions on how to install Awestruct and its dependencies, refer to the Install Awestruct section below.

Preview the site locally

To preview the site locally, simply run the default rake build task:

$ rake

The default rake build task is preview, so you’re effectively typing:

$ rake preview

The preview task is just a short way of invoking Awestruct in development mode directly:

$ awestruct -d

Now visit http://localhost:4242 to preview the site.

To rebuild the site from a clean state, pass the --force flag to the preview task:

$ rake preview[--force]

You can pass any flag through to Awestruct using the syntax in the previous command.

If you just want to generate the site, run:

$ rake gen

Add and commit files

Add new files (such as a new blog entry or image):

$ git add news/news-slug.adoc

or all new files present in a directory (it only affects new files, skips files already committed)

$ git add news/

Commit all files marked to be committed, including new files that were just added:

$ git commit -m 'your message here'

Commit all files that have changed, even if not marked to be committed:

$ git commit -a -m 'your message here'

Make sure there are no files that are "untracked" or "modified":

$ git status

You should see:

nothing to commit (working directory clean)

Now you are ready to deploy.

Install Awestruct

First, install RVM. Trust me on this.

$ curl -#L https://get.rvm.io | bash -s stable --ruby

Next, setup an RVM gemset for working with the Asciidoctor site:

$ rvm use 2.7 --create

At this point, you could install Awestruct directly, but since the site build has some additional dependencies, it’s best to let bundler handle the installation. Bundler will also ensure that you are using the correct versions of each gem when you run Awestruct.

$ bundle --path=.bundle/gems

You’re now Awestruct!

Hosting

This website is hosted on Netlify at the domain name asciidoctor.org. It’s managed by the account docbot [at] asciidoctor [dot] org and other Asciidoctor administrators.

Deployment

Netlify also handles generating and deploying the site. Deployment is triggered via a webhook on the default branch of the git repository. The deploy job executes the following command:

$ rake deploy:netlify

The version of Ruby is set using an environment variable in the Netlify configuration.

The deploy logs for asciidoctor.org can be viewed at https://app.netlify.com/sites/asciidoctor/deploys.

DNS

There are two DNS records that point asciidoctor.org and www.asciidoctor.org to the Netlify servers:

@ 3600 IN A 104.198.14.52
www 3600 IN CNAME asciidoctor.netlify.com.

The Netlify server automatically sets up a redirect that points from www.asciidoctor.org to asciidoctor.org.

TLS Certificate (https)

The TLS certificate for asciidoctor.org and www.asciidoctor.org was issued using Let’s Encrypt and is managed by Netlify.

Verify the certificate is valid using:

$ curl -vI https://asciidoctor.org

Look for CN=asciidoctor.org under the “Server certificate” section.

Thanks to Netlify, the certificate will be regenerated automatically when it nears its expiry date.

Licenses

The source code in this repository is licensed under the terms of the MIT license. See LICENSE to find the full license text.

The documentation content, located in the docs/ folder, is made available under the terms of a Creative Commons Attribution 4.0 International License (CC-BY-4.0).

See NOTICE for additional license, copyright, and trademark information.

asciidoctor.org's Issues

Update and Clarify Table Syntax in Quick Ref and Writers Guide

See conversation in this issue on Asciidoctor Core: 385

And add information regarding the new implicit header row described in issue 387

Spin off a more basic AsciiDoc syntax quick reference

Currently, the AsciiDoc syntax quick reference is trying to serve both newcomers and veteran users. The more complete it becomes, the more intimidating it makes the AsciiDoc syntax seem for newcomers.

Spin off a more basic AsciiDoc syntax quick reference that has the scope of a Markdown reference (specifically a Markdown variant, like Kramdown, that supports the most common extras).

Document various options for enabling custom substitutions

As this question comes up frequently, document explicitly the various ways to enable custom substitutions on a block, in particular a listing/source block.

Custom substitutions are supported on the source block (and any block, for that matter):

[source,java]
[subs="verbatim,quotes"]
----
System.out.println("Hello *bold* text").
----

If you want to enable the quotes in an ad-hoc way, then you'll want to enable macros on the block and use the inline pass:[] macro, which allows substitutions to be specified:

[source,java]
[subs="verbatim,macros"]
----
System.out.println("No *bold* here");
pass:verbatim,quotes[System.out.println("Hello *bold* text");]
----

The inline pass:[] macro does introduces additional markup into the Java source that makes it invalid in raw form, but the output it produces will be valid when viewed in a viewer (HTML, PDF, etc).

Related discussion post:
http://discuss.asciidoctor.org/Bold-Source-Code-and-Escaping-td464.html

Initial Draft of Producing your Document Guide

Guide includes the optional/alternate/advanced metadata and style attributes/values to customize the look and feel of your document.

What, Why, and Backend in AsciiDoc new users guide

As the goal of the new users guide is to be brief and to get them writing in AsciiDoc ASAP, I think most of the content prior to the Writing in AsciiDoc: First Steps section is just way too much backstory.

What do people think of removing most of that content and instead use it to create "What is AsciiDoc", "Why Use AsciiDoc", "How AsciiDoc Renders your Opus" guides?

Why does your syntax guide not match the canonical guide on Asciidoc site?

Your syntax guide is a subset of the canonical cheatsheet - http://powerman.name/doc/asciidoc.
For example, look at headers - you only seem to accept the

=== Header

style rather than

Header

It seems like your implementation is not correct if you don't match the original. Please make sure you match the original and canonical guide. 


For an example please see
https://github.com/thesteve0/osbeginnerguide/blob/master/Intro.asciidoc

Update the Editing with Live Preview doc

Update the Editing with Live Preview docs to feature all recommended approaches to editing AsciiDoc.

This page should include:

• DoctorFX / Doctorpad
• Guard and LiveReload plugins
• Gedit
• Sublime Text editor

And perhaps others as needed.

Add font awesome table check styles to Appendix A of User Manual

Change X's to use attribute check mark styles in header

Add asciidoctor-maven-plugin documentation to website

Transfer Asciidoctor Maven readme content to appropriate webpage

Document how to give attributes in the document precedence

In the AsciiDoc syntax quick ref, document how to give attributes in the document precedence over attributes defined by the caller (API or CLI).

Normally, an attribute defined by the caller overrides the attribute with the same name defined in the document. However, if you add a trailing @ to the attribute value, the declaration in the document takes precedence.

Add how to control substitution in URLs to User Manual

The base content is here: http://discuss.asciidoctor.org/Hyperlinks-with-multiple-underscores-td558.html

Create default start header for Docs

It's time to iterate over all the published Docs Headers and create a default header that can be pasted in as a good starting point when a new guide is created.
This will minimize the need to come up with link names that are used repeatedly and make sure each guide has the right attributes for the website stylesheet.

Below are just a few examples of how different the attribute lists are from Doc to Doc:

Example 1 (Header from Quick Ref):
:awestruct-layout: base
:awestruct-javascripts: [view-result]
:description: This guide is a quick reference for the common formatting markup and document elements in the AsciiDoc syntax.
:keywords: AsciiDoc, Asciidoctor, syntax, reference, cheatsheet
:imagesdir: ../images
:toc:
:toc-placement!:
ifndef::awestruct[]
:idprefix:
:idseparator: -
endif::awestruct[]
:result: role="result"
:linkattrs:

Example 2 (Header from MacOSX Guide)
:awestruct-layout: base
:toc:
:toolchain: link:

Example 3: (Header from How do I render....)
:awestruct-layout: base
:toc:

Examples of the variety of link naming schemes:

Example 1: (Header links from How do I render...)
:toolchain: link:/docs/install-toolchain
:buildref: http://github.com/asciidoctor/asciidoctor-stylesheet-factory/blob/master/README.adoc
:factoryrepo: http://github.com/asciidoctor/asciidoctor-stylesheet-factory
:factoryshowcase: http://themes.asciidoctor.org/
:customthemeref: http://github.com/asciidoctor/asciidoctor-stylesheet-factory/blob/master/README.adoc#create-a-new-theme
:yelp: http://live.gnome.org/Yelp
:publican: http://fedorahosted.org/publican
:a2x: http://asciidoc.org/a2x.1.html
:backendrepo: http://github.com/asciidoctor/asciidoctor-backends
:backendissue: http://github.com/asciidoctor/asciidoctor-backends/issues
:mailinglist: http://discuss.asciidoctor.org/
:userguide: http://asciidoc.org/userguide.html

Example 2: (Header links from Writers Guide)
:asciidoc-ref: http://asciidoc.org
:asciidoc-dl-ref: http://sourceforge.net/projects/asciidoc/files/latest/download
:asciidoc-editor-ref: http://asciidoc.org/#_editor_support
:asciidoc-faq-ref: http://asciidoc.org/faq.html
:asciidoc-guide-ref: http://asciidoc.org/userguide.html
:asciidoc-install-ref: http://asciidoc.org/INSTALL.html
:asciidoc-list-ref: http://groups.google.com/group/asciidoc
:asciidoctor-ref: link:/
:asciidoctor-gem-ref: https://rubygems.org/gems/asciidoctor
:deckjs-ref: http://imakewebthings.com/deck.js
:editing-ref: link:/docs/editing-asciidoc-with-live-preview/
:gist-ref: http://gist.github.com
:publican-ref: https://fedorahosted.org/publican
:quick-ref: link:/docs/asciidoc-quick-reference/
:what-asciidoc-ref: link:/docs/what-is-asciidoc-why-use-it

Add Installing the Toolchain documentation to the website

Remove links to ReadME from documentation index
Will include instructions for both Asciidoctor, AsciiDoc, and a2x

Update Docs Index page with links to Asciidoclet and Asciidoctor.js documentation

Docs have been published by index page lacks links.

Refer to comments in this pull request: #55

Remove differences between AsciiDoc and Asciidoctor from homepage

This information is now available in the Docs section under How do Asciidoctor and AsciiDoc differ?

Ref: Pull Request #92

Edit and recompile differences between Asciidoctor and AsciiDoc list

Have difference as their own .adoc
Add new link to Docs index page

Upload demo of deck.js slides showcasing attributes

This is almost done, I just need to polish it and pick a picture.

• Add link in deck.js guide

Update Maven docs

Add and update content per new release and new funtions

Write a tutorial for how to blog with AsciiDoc and Awestruct

Write a tutorial that covers how to write a blog entry in AsciiDoc for an Awestruct site*.

Here's a rough outline that identifies the scope of the tutorial:

• Motivation / vision (short and sweet)
  • Using a lightweight markup language makes it easy to focus on content and write
  • Preview on GitHub (don't need to build site just to see it)
  • Collaboration via pull requests
  • Can revise or even create directly online
• A brief section (or link to another tutorial) about setting up Awestruct to use as a blog
• Creating a new file for a blog entry
  • Where to put it (blog/ folder)
  • What to name it (file name becomes URL "slug")
  • What file extension to use (.ad is where we want to get, but .adoc is required for GitHub preview now)
• Blog entry header
  • Blog title
  • Author (can we set a default author?)
  • Date (soft date, will be updated by script)
  • Tags (:awestruct-tags: [tag1, tag2])
  • imagesdir: ../images (important for image preview on GitHub)
  • Draft (:awestruct-draft: true) to prevent automatic publishing
• Blog entry content
  • just AsciiDoc, refer to AsciiDoc Writer's Guide
  • put images in images/ folder, reference path relative to that folder (e.g. image:sky.jpg[])
• Publishing GitHub pages
  • Set timezone in _config/site.yml
  • Rakefile for setting date according to time-zone
  • Link to tutorial about automatic publishing of Awestruct site to GitHub pages via Travis CI
• Customizing AsciiDoc output using templates (perhaps not in first version)

* We may be able to update this tutorial in the future to include steps for using other static-site generation tools once they offer similar AsciiDoc integration to Awestruct.

Add deckjs backend documentation

Render ReadMe to the Docs section
Update the Index page

Add stylesheet factory documentation to website

Pull the content from the stylesheet factory website into the documentation

Integrate user manual template

Add parts and sections from template into user manual to determine what documentation is missing.

Write Release Notes news post

• tag with draft
• incorporate header attributes
• @mojavelinux writes intro
• edit Release Notes
• incorporate release notes template
• embed release notes

Can an article have multiple level 0 titles? Re: Newbies Guide clarification

In the new users guide it says:

Section levels cannot be chosen arbitrarily. There are two rules you must follow:

1. A document can only have a single level 0 section (in addition to the document title) if the doctype is set to book (the default is article)

Does this mean that other doctypes can have multiple level 0 sections or can they have none?

Document how to link stylesheet when processing subdirectories

In response to a question raised on the mailinglist, document how to link to a common stylesheet location when processing documents in subdirectories.

For more details and proposed solutions, see the following mailinglist thread:

http://discuss.asciidoctor.org/Single-CSS-for-multiple-nested-adoc-files-td552.html

Update Maven plugin guide with 0.1.3.1 information

Add:

• artifact links
• new configuration options
• built-in attributes
• multiple outputs for the same file

Create a table of all recognized attributes and the accepted values

Create a table that catalogs all the attributes recognized by Asciidoctor and the acceptable values. Include a description of each attribute, where it can be specified (cli, document, etc) and under what circumstances.

Provide clarification for constrained and unconstrained quotes

Add the following clarification to the writer's guide and quick reference (if it fits).

Constrained means "around a word". Unconstrained means "anywhere".

Authorinfo is incorrect for docbook backend

I have this input:

RHQ
===
Heiko W. Rupp <[email protected]>
:Author Initials: HWR
:toc:
:icons:
:numbered:
:website: http://www.pilhuhn.de/hwr
:author: Heiko W. Rupp`

asciidoc creates

<bookinfo>
    <title>RHQ</title>
    <author>
        <firstname>Heiko</firstname>
        <othername>W.</othername>
        <surname>Rupp</surname>
        <email>[email protected]</email>
    </author>
    <authorinitials>HWR</authorinitials>
</bookinfo>

(see the correct split into firstname and surname etc.

asciidoctor creates

<bookinfo>
  <title>RHQ</title>
  <date>2013-01-31</date>
  <author>
    <firstname>Heiko W. Rupp <[email protected]></firstname>
  </author>
  <authorinitials>HWR</authorinitials>

rename the asciidoctor.github.com repository to asciidoctor.org

To make the purpose / function of this repository more clear, rename it to asciidoctor.org.

The following steps need to be performed to complete this change:

1. Rename this repository to asciidoctor.org (enabled option to forward requests from the old url to the new one)
2. Rename the master branch to gh-pages
3. Rename the develop branch to master (or just keep it as develop)
4. Update the branch names in the Awestruct configuration (_config/site.yml)
5. Update the branch names in the Rakefile (if necessary)
6. Make sure Travis notices the change and test a publish to verify

Write blog post featuring new syntax and major fixes for 0.1.3 release

Include code snippets showing new attributes and Font Awesome icons.
Link to appropriate guides with updated/expanded examples.

Upgrade website to use Asciidoctor 0.1.4

This will need to be done so the examples in the release notes display correctly.

Update user manual with last minute 0.1.4 ToC syntax changes

right now works with multiple attributes

Add extensions section to user manual

Pull base content from the 0.1.4 release notes and this discussion:

http://discuss.asciidoctor.org/Finally-a-draft-of-the-Asciidoctor-extension-API-has-landed-td455.html

Add link to conversion script (Confluence XHTML to AsciiDoc)

Add a link to the following script on the migrations page that converts Confluence XHTML to AsciiDoc:

https://gist.github.com/melix/6020336

Write differences between AsciiDoc and Markdown documentation

How do the two syntaxes differ?
Partners with the Asciidoctor and AsciiDoc differences
May go under The Basics category

Installation Doc - first section AsciiDoc or Asciidoctor?

In the installation guide, should the Asciidoctor instructions come first?
Per @mojavelinux comment when doc was first published to website.

Incorporate default Asciidoctor stylesheet into website

The styles on asciidoctor.org are similar to the ones from the default Asciidoctor stylesheet, but does not share a common build. That means every change to the default Asciidoctor stylesheet also has to be made to the website.

Incorporate the default Asciidoctor stylesheet into the website so that the website can inherit the styles needed for styling HTML generated by Asciidoctor.

Move Markdown syntax in Quick Ref Guide

Move the Markdown syntax to its own section at the bottom of the Quick Ref guide.

Document acceptable formats for video macro

Not all video formats can be used with the video tag. Make a note of this in the documentation / writer's guide. Something along the lines of:

The HTML 5 video tag does not support the Quicktime/Sorenson format for video. It first needs to be converted to a "web-friendly" video format. That explains why nothing happens when you press the play button.

The following article is an excellent resource for explaining how to prepare video for an HTML 5 page.

http://www.htmlgoodies.com/html5/client/how-to-embed-video-using-html5.html#fbid=ensvc_rW_lt

You can ignore the parts about the HTML elements since Asciidoctor is already generates that. What's important are the video formats.

* While there are ways to embed Quicktime/Sorenson using object/embed tags, these are considered deprecated and using a web-friendly video format is strongly recommended.

Create a page that lists / recommends editors

People are often asking which editor they should use for AsciiDoc (phrased as "what's a good AsciiDoc editor?"). Of course, our stance is that you don't need a special editor. We can make that point, but also recommend editors that have good syntax highlighting and perhaps embedded preview.

We want to make sure to recommend open source options first, but I guess it would be biased if we didn't list non-open source editors that are know to be very good (such as Sublime).

Update Gradle guide with latest release information

Include new properties and configuration options

Create a showcase page

The showcase page should highlight places where Asciidoctor is used, projects that build on it and projects that integration with it.

Examples include:

• github.com
• Awestruct
• Doctorpad / DoctorFX
• sandoc
• etc.

We should also add a testimonials page. If that should be a different page than this one, split that off into another issue (best not to bundle issues).

Add documentation about rendering output and backends

Include updates per Asciidoctor 0.1.2

Line wrap example in newbies guide wrong?

I can't see a difference between the text written in AsciiDoc syntax to showcase wrapping and the rendered output. If I'm reading the example correctly, I think the output is supposed to be wrapped...but it's not. So either the example text is wrong or the explanation of the example is wrong.

From document:
In other words, you write AsciiDoc like you’re writing an e-mail.

Wrapping lines of text:

Adjacent lines like these are combined to form a single paragraph.
That means you can wrap paragraph text
or put each sentence on a separate line
and the line breaks won't appear in the output.

Here’s how the previous lines look when rendered:

Adjacent lines like these are combined to form a single paragraph.
That means you can wrap paragraph text
or put each sentence on a separate line
and the line breaks won't appear in the output.

Add asciidoctor-gradle-plugin documentation to website

Add content from the project's readme to the documentation website.

Create a navigation toc for the quick reference guide

After using the quick reference guide for myself, I realize it is long and scrolling up and down it looking for a specific tip gets tiring.

Update new features into AsciiDoc Syntax Reference

There are some amazing aspects released on Asciidoctor 0.1.3 that are documented in news section but not in AsciiDoc Syntax Quick Reference. I think would be good have all features documented in a single document so anyone new can learn all features without having to read more than one document.

Add java integration documentation to Docs webpage

Render Alex's java integration ReadMe on the website and interconnect it with the other guides.
Update the index page

Create 404 page

Be a little crazy