<![CDATA[Randy Butternubs]]>https://spikebachman.github.ioRSS for NodeThu, 21 Jul 2016 20:30:54 GMT60<![CDATA[A quick reference guide to my most commonly used AsciiDoc syntax.]]>

Full references can be found at:

Ref http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ and http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

HubPress uses the AsciiDoc markup — not to be confused with AsciiDoctor.
As of 7/20/06, the ghostium theme seems to be the only theme that is rendering the AsciiDoc syntax in the same way as the quick reference guide.
Paragraphs

Paragraphs don’t require any special markup in AsciiDoc. A paragraph is just one or more lines of consecutive text.

To begin a new paragraph, separate it by at least one blank line.

Line breaks view result

Rubies are red, + Topazes are blue.

[%hardbreaks] Ruby is red. Java is black.

Literal view result

A normal paragraph.

A sequence of lines that begin with at least one space is a literal paragraph.
Literal paragraphs are treated as preformatted text. The text is shown in a
fixed-width font and endlines are preserved.

Another normal paragraph.

Admonition view result

An admonition paragraph draws the reader’s attention to auxiliary information. Its purpose is determined by the label at the beginning of the paragraph.

Here are the other built-in admonition types:

Pro tip…​
Don’t forget…​
Watch out for…​
Ensure that…​ 
You can also create admonition blocks. Lead paragraph view result

[.lead] This text will be styled as a lead paragraph (i.e., larger font).

The default Asciidoctor stylesheet automatically styles the first paragraph of
the preamble as a lead paragraph. More Paragraph, Admonition and Literal Block
Examples

See these sections in the Asciidoctor User Manual for more information and examples.

Paragraphs
Literal Text and Blocks
Admonitions

Formatted Text Bold, Italic, and Monospace view result

italic phrase

italic letters

bold phrase

bold letters

bold italic phrase

bold italic letters

monospace phrase and letters

monospace italic phrase and letters

monospace bold phrase and letters

monospace bold italic phrase and letters

Custom Styling view result

Werewolves are allergic to cinnamon.

Do werewolves believe in small print?

Once upon an infinite loop.

Superscript and Subscript view result

superscript phrase

subscript phrase

Curved Quotation Marks and Apostrophes view result

‘single curved quotes’

“double curved quotes”

Olaf’s desk was a mess.

All of the werewolves’ desks were a mess.

Olaf had been with the company since the ’60s.

More Text Formatting Examples

See these sections in the Asciidoctor User Manual for more information and examples.

Bold and Italic Formatting
Quotation Marks and Apostrophes
Subscript and Superscript
Monospace Formatting
Custom Styling with Attributes
Passthrough Macros

Document Header A header is optional. The header may not contain blank lines and must be offset from the content by at least one blank line. Title only

My Document’s Title

My document provides…​

Title and author line

My Document’s Title Doc Writer <doc.writer@asciidoctor.org>

My document provides…​

Asciidoctor allows multiple authors in the author line. Use the semi-colon
character to separate each author. Title, author line and revision line

My Document’s Title Doc Writer <doc.writer@asciidoctor.org> v1.0, 2014-01-01

My document provides…​

You cannot have a revision line without an author line. Document header with
attributes

My Document’s Title Doc Writer <doc.writer@asciidoctor.org> v1.0, 2014-01-01

My document provides…​

Section Titles (Headings) Article doctype view result

Document Title (Level 0)

Level 1 Section Title

Level 2 Section Title

Level 3 Section Title

Level 4 Section Title
Level 5 Section Title

Another Level 1 Section Title

When using the article doctype (the default), you can only have one level-0
section title (i.e., the document title) and it must be in the document
header. The number of equal signs matches the heading level in the HTML
output. For example, Section Level 1 becomes an <h2> heading. Book doctype
view result

Document Title (Level 0)

Section Level 1

Section Level 2

Section Level 3

Section Level 4
Section Level 5

Section Level 0

Explicit id

== Primitive types and null values

Section anchors and links (Asciidoctor only)

sectanchors

When this document attribute is set, a section icon anchor appears in front
of the section title. sectlinks
When this document attribute is set, the section titles become self-links.
This enables a reader to bookmark the section.
Section title anchors depend on the default Asciidoctor stylesheet to render
properly. Include Files Document parts

Reference Documentation Lead Developer

This is documentation for project X.

Unresolved directive in <stdin> - include::basics.adoc[]

Unresolved directive in <stdin> - include::installation.adoc[]

Unresolved directive in <stdin> - include::example.adoc[]

Asciidoctor does not insert blank lines between adjacent include statements to
keep the content separated. Be sure to add a blank line in the source document
to avoid unexpected results, such as a section title being swallowed. Include
content from a URI

https://raw.githubusercontent.com/asciidoctor/asciidoctor/master

HubPress

A free, open source tool you can use to build a blog using GitHub Pages and AsciiDoc.

HubPress on Gratipay 1744073?v=3&s=24.

1. What Is HubPress?

editor.png

HubPress is a web application that makes it easy for you to maintain a blog. It provides the following features:

  • WYSIWYG editor for writing blog posts.

  • Backed by the power of AsciiDoc markup for tight control of content presentation to your requirements.

  • Administration console to customise many aspect of your blog’s content.

  • Disqus integration for blog comments.

  • Google Analytics integration to track visitor activity.

  • A number of different themes shipped with the product, ready to use.

Hosting for your blog is provided by GitHub Pages.

If you see something wrong with the documentation, please raise an issue. Your help with improving every aspect of HubPress is greatly appreciated. Pull Requests are always welcome.

See the Contributors Guide for more information about being a successful HubPress contributor.

2. Browser Compatibility

HubPress is compatible with Chrome Desktop, Firefox Desktop, and Chrome for Android.

3. Getting Started

3.1. Fork the Repository

Click the Fork icon Fork to create a copy of this repository within your GitHub account.

3.2. Use the github.io Domain

If you have never used your GitHub Pages domain before, you can use this procedure to quickly set up HubPress. With this method, only a few steps are required to get HubPress deployed and ready for use.

If you are currently using your username.github.io GitHub Pages domain for another project, or if you want to use a custom domain name, skip to the next procedure for instructions.

  1. Rename your repository to <username>.github.io

  2. Set values in hubpress/config.json

    Edit config

    The following parameters are mandatory:

    • username, which is your GitHub user name,

    • repositoryName, which is the new name of the repository fork, <username>.github.io.

  3. Commit the changes, and open the GitHub Pages domain: https://<username>.github.io/.

  4. The following screen indicates you have correctly configured HubPress

    Install complete

3.3. Use a Custom Domain or GitHub Page Domain Already In Use

If you want your blog to be available on a custom domain, or you are already using your GitHub Pages domain to host another project, some extra configuration is required.

  1. In the repository settings, set the default branch to gh-pages:

    Settings gh-pages

  2. Switch your repository to the gh-pages branch.

    Install complete

  3. Set the required values in hubpress/config.json

    Edit config

    The following parameters are mandatory:

    • username, which is your GitHub user name,

    • repositoryName, which is the repository fork. For example, hubpress.io if you did not rename it.

  4. Commit the changes, and open the GitHub Pages domain: https://<username>.github.io/<repositoryName>/.

  5. The following screen indicates you have correctly configured HubPress

    Install complete

Now you have successfully configured HubPress, you can customise it by adding social network information, experiment with different themes, and make your HubPress blog your own.

See the Administration Guide for the next steps you need to take in setting up your HubPress blog.

Once you’ve completed the configuration aspects, you can write your first blog post. Follow the guidelines in the Writer’s Guide to write a sucessful first blog post.

4. HubPress Team

Code by Anthonny Quérouil (Twitter - @anthonny_q).

English Docs by Jared Morgan (Twitter - @jaredmorgs).

Translations (Japanese) by:

5. Donations

HubPress is now on Gratipay!

7b09da22 ceb9 11e5 93f7 16ab135b2e2e.png

It’s not the only way you can help us, but it is certainly a welcome one. Donations are a great way to show your appreciation for the platform: it inspires us to dedicate extra time away from our families and day jobs to make HubPress an awesome blogging platform for you.

cc5ee908 ceb9 11e5 9d8b c526f081f1e9.png 
Including content from a URI is potentially dangerous, so it’s disabled if the
safe mode is SECURE or greater. Assuming the safe mode is less than SECURE,
you must also set the allow-uri-read attribute to permit Asciidoctor to read
content from a URI. Horizontal Rules and Page Breaks Horizontal rule view
result

Page break

Lists Unordered, basic view result

  • Edgar Allen Poe Sheri S. Tepper Bill Bryson

    Blank lines are required before and after a list. You can force two lists
apart with a line comment, as the previous example demonstrates. The text in
the comment, (^), is optional, but serves as a hint to other authors that this
line serves as an “end of list” marker. Unordered, max nesting view result

  • level 1 level 2 * level 3 * level 4 ** level 5 level 1

    The unordered list marker can be changed using block styles. Checklist view
result

    • checked [x] also checked [ ] not checked normal list item

      Checklists can use font-based icons and be interactive. Ordered, basic view
result

      1. Step 1 . Step 2 . Step 3

Ordered, nested view result

  1. Step 1 . Step 2 .. Step 2a .. Step 2b . Step 3

Ordered, max nesting view result

  1. level 1 .. level 2 …​ level 3 …​. level 4 …​.. level 5 . level 1

    For ordered lists, Asciidoctor supports numeration styles such as lowergreek
and decimal-leading-zero. Labeled, single-line view result
    first term

    definition of first term section term:: definition of second term

Labeled, multi-line view result

first term

definition of first term section term:: definition of second term

Q&A view result

[qanda] What is Asciidoctor?

An implementation of the AsciiDoc processor in

Ruby. What is the answer to the Ultimate Question?

42

Mixed view result

Operating Systems

Linux::: . Fedora * Desktop . Ubuntu * Desktop * Server

BSD

. FreeBSD . NetBSD

Cloud Providers

PaaS::: . OpenShift . CloudBees IaaS::: . Amazon EC2 . Rackspace

Lists can be indented. Leading whitespace is not significant. Complex content
in outline lists view result

  • Every list item has at least one paragraph of content, which may be wrapped,

  • even using a hanging indent. + Additional paragraphs or blocks are adjoined by

  • putting a list continuation on a line adjacent to both blocks. + list

* continuation

a plus sign (+) on a line by itself

  • A literal paragraph does not require a list continuation.

    $ gem install asciidoctor

  • AsciiDoc lists may contain any complex content. + [cols="2", options="header"] |===

  • |Application |Language

|AsciiDoc |Python

|Asciidoctor |Ruby |===

Links External view result

http://asciidoctor.org - automatic!

Asciidoctor

Asciidoctor @ GitHub

With spaces and special characters view result

URL with special characters

URL with special characters

Windows path view result

Whitepaper

Relative view result

Docs

Email and IRC view result

devel@discuss.arquillian.org

Discuss Arquillian

Subscribe, Subscribe me, I want to join!

irc://irc.freenode.org/#asciidoctor

Link with attributes (Asciidoctor only) view result

Discuss Asciidoctor, role="external", window="_blank"

Discuss Asciidoctor

"Google, Yahoo, Bing^", role="teal"

Links with attributes (including the subject and body segments on mailto
links) are a feature unique to Asciidoctor. To enable them, you must set the
linkattrs attribute on the document. When they are enabled, you must quote the
link text if it contains a comma. Inline anchors view result

Inline anchors make arbitrary content referenceable.

Use a cross reference to link to this location.

The xreflabel attribute will be used as link text in the cross-reference link.

Internal cross references view result

See [paragraphs] to learn how to write paragraphs.

Learn how to organize the document into sections.

Inter-document cross references (Asciidoctor only)

Refer to Section B for more information.

See you when you get back from Section B!

Images Block view result

sunset.jpg
Sunset

image::sunset.jpg[caption="Figure 1: ", title="A mountain sunset", alt="Sunset", width="300", height="200", link="http://www.flickr.com/photos/javh/5448336655"]

GitHub mascot 
Images are resolved relative to the value of the imagesdir document attribute,
which defaults to an empty value. The imagesdir attribute can be an absolute
path, relative path or base URL. If the image target is a URL or absolute
path, the imagesdir prefix is not added. You should use the imagesdir
attribute to avoid hard coding the shared path to your images in every image
macro. Image macro using positioning role view result

Sunset What a beautiful sunset!

There are a variety of attributes available to position and frame images.
Inline view result

Click Play to get the party started.

Click pause.png when you need a break.

Embedded

Document Title :data-uri:

When the data-uri attribute is set, all images in the document—​including
admonition icons—​are embedded into the document as data URIs. Instead of
declaring the data-uri attribute in the document, you can pass it as a
command-line argument using -a data-uri. Videos Block

Embedded Youtube video

Embedded Vimeo video

You can control the video settings using additional attributes and options on
the macro. Source Code Inline view result

Reference code like types or methods inline.

Literal line view result

Indent the line one space to insert a code snippet

Literal block view result

  1. error: The requested operation returned error: 1954 Forbidden search for defensive operations manual absolutely fatal: operation initiation lost in the dodecahedron of doom would you like to die again? y/n …​.

Listing block with title, no syntax highlighting view result

Gemfile.lock ---- GEM remote: https://rubygems.org/ specs: asciidoctor (0.1.4)

PLATFORMS ruby

DEPENDENCIES asciidoctor (~> 0.1.4) ----

Code block with title and syntax highlighting view result

[source,ruby] .app.rb ---- require 'sinatra'

get '/hi' do "Hello World!" end ----

Code block with callouts view result

[source,ruby] ---- require 'sinatra' // <1>

get '/hi' do // <2> "Hello World!" // <3> end ---- <1> Library import <2> URL mapping <3> Content for response

Code block with non-selectable callouts view result

---- line of code  // <1> line of code  # <2> line of code  ;; <3> --(1)

A callout behind a line comment for C-style languages. <2> A callout behind

a line comment for Ruby, Python, Perl, etc. <3> A callout behind a line

comment for Clojure.

XML code block with a non-selectable callout view result

[source,xml] ---- <section> <title>Section Title</title> <!--1-→ </section> ---- <1> The section title is required.

Code block sourced from file

[source,ruby] ---- include::app.rb[] ----

Code block sourced from file relative to source directory

[source,java] ---- include::src/main/java/org/asciidoctor/Asciidoctor.java[] ----

Strip leading indentation from source

[source,ruby,indent=0] ---- include::lib/document.rb[lines=5..10] ----

When indent is 0, the leading block indent is stripped (tabs are replaced
with 4 spaces).
When indent is > 0, the leading block indent is first stripped (tabs are
replaced with 4 spaces), then a block is indented by the number of columns
equal to this value.

Code block without delimiters (no blank lines) view result

[source,xml] <meta name="viewport" content="width=device-width, initial-scale=1.0">

This is normal content.

Enabling the syntax highlighter

Syntax highlighting is enabled by setting the source-highlighter attribute in the document header or passed as an argument.

The valid options are coderay, highlightjs, prettify, and pygments. More Delimited Blocks Sidebar view result

AsciiDoc history ** AsciiDoc was first released in Nov 2002 by Stuart

Rackham. It was designed from the start to be a shorthand syntax for producing professional documents like DocBook and LaTeX. **

Any block can have a title, positioned above the block. A block title is a
line of text that starts with a dot. The dot cannot be followed by a space.
Example view result
Sample document ==== Here’s a sample AsciiDoc document:

[listing] …​. = Title of Document Doc Writer :toc:

This guide provides…​ …​.

The document header is useful, but not required. ====

Admonition view result

[NOTE] ==== An admonition block may contain complex content.

A list - one - two - three

Another paragraph. ====

Admonition and callout icons

Asciidoctor can “draw” icons using Font Awesome and CSS.

To use this feature, set the value of the icons document attribute to font. Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each admonition block.

Icons can also be used inline and styled. Blockquote view result

[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg] _ Four score and seven years ago our fathers brought forth on this continent a new nation…​ _

[quote, Albert Einstein] A person who never made a mistake never tried anything new.

_ A person who never made a mistake never tried anything new. _

[quote, Charles Lutwidge Dodgson, 'Mathematician and author, also known as Lewis Carroll'] _ If you don’t know where you are going, any road will get you there. _

Abbreviated blockquote (Asciidoctor only) view result

"I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical." — Thomas Jefferson, Papers of Thomas Jefferson: Volume 11

Air quotes: the best thing since fenced code blocks (Asciidoctor only) view result

[, Richard M. Nixon] "" When the President does it, that means that it’s not illegal. ""

Passthrough view result

<p> Content in a passthrough block is passed to the output unprocessed. That means you can include raw HTML, like this embedded Gist: </p>

<script src="http://gist.github.com/mojavelinux/5333524.js"> </script>

Open view result

 — An open block can be an anonymous container, or it can masquerade as any

other block. — 

[source] — puts "I’m a source block!" — 

Custom substitutions view result

[source,xml,subs="verbatim,attributes"] ---- <dependency> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-java-integration</artifactId> <version>0.1.4</version> </dependency> ----

Block Id, Role and Options Traditional markup method for assigning block id and role

[role="incremental"] * Goal 1 * Goal 2

Shorthand markup method for assigning block id and role (Asciidoctor only)

[#goals.incremental] * Goal 1 * Goal 2

To specify multiple roles using the shorthand syntax, separate them by dots.
The order of id and role values in the shorthand syntax does not matter.

Traditional markup method for assigning quoted text anchor (id) and role

free the world

Shorthand markup method for assigning quoted text anchor (id) and role (Asciidoctor only)

free the world

Role assigned to text enclosed in backticks

monospace text

Traditional markup method for assigning block options

[options="header,footer,autowidth"] |=== |Cell A |Cell B |===

Shorthand markup method for assigning block options (Asciidoctor only)

[%header%footer%autowidth] |=== |Cell A |Cell B |===

Comments Line

Single-line comments can be used to divide elements, such as two adjacent
lists. Block
]]>https://spikebachman.github.io/2016/07/20/A-quick-reference-guide-to-my-most-commonly-used-Ascii-Doc-syntax.htmlhttps://spikebachman.github.io/2016/07/20/A-quick-reference-guide-to-my-most-commonly-used-Ascii-Doc-syntax.htmlWed, 20 Jul 2016 00:00:00 GMT<![CDATA[Second Post]]>

Hrmmm. First post didn’t quite work out.

Turns out it’s always good to read documentation first. (I dislike reading documentation.)

How do I save this thing???

19138612090 3af4d7b716 k.jpg>
]]>https://spikebachman.github.io/2016/07/19/Second-Post.htmlhttps://spikebachman.github.io/2016/07/19/Second-Post.htmlTue, 19 Jul 2016 00:00:00 GMT