Module Asciidoctor
In: lib/asciidoctor.rb
lib/asciidoctor/debug.rb
lib/asciidoctor/substituters.rb
lib/asciidoctor/backends/base_template.rb
lib/asciidoctor/backends/_stylesheets.rb
lib/asciidoctor/backends/html5.rb
lib/asciidoctor/backends/docbook45.rb
lib/asciidoctor/section.rb
lib/asciidoctor/inline.rb
lib/asciidoctor/table.rb
lib/asciidoctor/version.rb
lib/asciidoctor/path_resolver.rb
lib/asciidoctor/list_item.rb
lib/asciidoctor/abstract_block.rb
lib/asciidoctor/lexer.rb
lib/asciidoctor/renderer.rb
lib/asciidoctor/block.rb
lib/asciidoctor/attribute_list.rb
lib/asciidoctor/helpers.rb
lib/asciidoctor/callouts.rb
lib/asciidoctor/document.rb
lib/asciidoctor/reader.rb
lib/asciidoctor/cli/options.rb
lib/asciidoctor/cli/invoker.rb
lib/asciidoctor/abstract_node.rb

Public: Methods for parsing Asciidoc input files and rendering documents using eRuby templates.

Asciidoc documents comprise a header followed by zero or more sections. Sections are composed of blocks of content. For example:

  Doc Title
  =========

  SECTION 1
  ---------

  This is a paragraph block in the first section.

  SECTION 2

  This section has a paragraph block and an olist block.

  1. Item 1
  2. Item 2

Examples:

Use built-in templates:

  lines = File.readlines("your_file.asc")
  doc = Asciidoctor::Document.new(lines)
  html = doc.render
  File.open("your_file.html", "w+") do |file|
    file.puts html
  end

Use custom (Tilt-supported) templates:

  lines = File.readlines("your_file.asc")
  doc = Asciidoctor::Document.new(lines, :template_dir => 'templates')
  html = doc.render
  File.open("your_file.html", "w+") do |file|
    file.puts html
  end

Methods

load   load_file   render   render_file   save_to  

Classes and Modules

Module Asciidoctor::Cli
Module Asciidoctor::Debug
Module Asciidoctor::DocBook45
Module Asciidoctor::EmptyTemplate
Module Asciidoctor::HTML5
Module Asciidoctor::Helpers
Module Asciidoctor::SafeMode
Module Asciidoctor::Substituters
Class Asciidoctor::AbstractBlock
Class Asciidoctor::AbstractNode
Class Asciidoctor::AttributeList
Class Asciidoctor::BaseTemplate
Class Asciidoctor::Block
Class Asciidoctor::Callouts
Class Asciidoctor::Document
Class Asciidoctor::Inline
Class Asciidoctor::Lexer
Class Asciidoctor::ListItem
Class Asciidoctor::PathResolver
Class Asciidoctor::Reader
Class Asciidoctor::Renderer
Class Asciidoctor::Section
Class Asciidoctor::Table

Constants

ROOT_PATH = File.expand_path(File.join(File.dirname(__FILE__), '..'))   The root path of the Asciidoctor gem
FORCE_ENCODING = RUBY_VERSION > '1.9' && Encoding.default_external != Encoding::UTF_8   Flag to indicate whether encoding of external strings needs to be forced to UTF-8 All input data must be force encoded to UTF-8 if Encoding.default_external is not UTF-8 Address failures performing string operations that are reported as "invalid byte sequence in US-ASCII" Ruby 1.8 doesn‘t seem to experience this problem (perhaps because it isn‘t validating the encodings)
DEFAULT_DOCTYPE = 'article'   The default document type Can influence markup generated by render templates
DEFAULT_BACKEND = 'html5'   The backend determines the format of the rendered output, default to html5
DEFAULT_STYLESHEET_KEYS = ['', 'DEFAULT'].to_set
DEFAULT_STYLESHEET_NAME = 'asciidoctor.css'
BACKEND_ALIASES = { 'html' => 'html5', 'docbook' => 'docbook45'   Pointers to the preferred version for a given backend.
DEFAULT_PAGE_WIDTHS = { 'docbook' => 425   Default page widths for calculating absolute widths
DEFAULT_EXTENSIONS = { 'html' => '.html', 'docbook' => '.xml', 'asciidoc' => '.ad', 'markdown' => '.md'   Default extensions for the respective base backends
SECTION_LEVELS = { '=' => 0, '-' => 1, '~' => 2, '^' => 3, '+' => 4
ADMONITION_STYLES = ['NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION'].to_set
PARAGRAPH_STYLES = ['comment', 'example', 'literal', 'listing', 'normal', 'pass', 'quote', 'sidebar', 'source', 'verse', 'abstract', 'partintro'].to_set
VERBATIM_STYLES = ['literal', 'listing', 'source', 'verse'].to_set
DELIMITED_BLOCKS = { '--' => [:open, ['comment', 'example', 'literal', 'listing', 'pass', 'quote', 'sidebar', 'source', 'verse', 'admonition', 'abstract', 'partintro'].to_set], '----' => [:listing, ['literal', 'source'].to_set], '....' => [:literal, ['listing', 'source'].to_set], '====' => [:example, ['admonition'].to_set], '****' => [:sidebar, Set.new], '____' => [:quote, ['verse'].to_set], '""' => [:quote, ['verse'].to_set], '++++' => [:pass, Set.new], '|===' => [:table, Set.new], ',===' => [:table, Set.new], ':===' => [:table, Set.new], '!===' => [:table, Set.new], '////' => [:comment, Set.new], '```' => [:fenced_code, Set.new], '~~~' => [:fenced_code, Set.new]
BREAK_LINES = { %q{'''} => :ruler, '<<<' => :page_break
LIST_CONTEXTS = [:ulist, :olist, :dlist, :colist]
NESTABLE_LIST_CONTEXTS = [:ulist, :olist, :dlist]
ORDERED_LIST_STYLES = [:arabic, :loweralpha, :lowerroman, :upperalpha, :upperroman]
ORDERED_LIST_MARKER_PATTERNS = { :arabic => /\d+[.>]/, :loweralpha => /[a-z]\./, :upperalpha => /[A-Z]\./, :lowerroman => /[ivx]+\)/, :upperroman => /[IVX]+\)/
ORDERED_LIST_KEYWORDS = { 'loweralpha' => 'a', 'lowerroman' => 'i', 'upperalpha' => 'A', 'upperroman' => 'I'
LIST_CONTINUATION = '+'
LINE_BREAK = ' +'
BLANK_LINE_PATTERN = /^[[:blank:]]*\n/   NOTE allows for empty space in line as it could be left by the template engine
LINE_FEED_ENTITY = '&#10;'
COMPLIANCE = { # AsciiDoc terminates paragraphs adjacent to # block content (delimiter or block attribute list) # Compliance value: true # TODO what about literal paragraph? :block_terminates_paragraph => true, # AsciiDoc does not treat paragraphs labeled with a # verbatim style (literal, listing, source, verse) # as verbatim; override this behavior # Compliance value: false :strict_verbatim_paragraphs => true, # AsciiDoc allows start and end delimiters around # a block to be different lengths # this option requires that they be the same # Compliance value: false :congruent_block_delimiters => true, # AsciiDoc will recognize commonly-used Markdown syntax # to the degree it does not interfere with existing # AsciiDoc behavior. :markdown_syntax => true   Flags to control compliance with the behavior of AsciiDoc
REGEXP = { # NOTE: this is a inline admonition note :admonition_inline => /^(#{ADMONITION_STYLES.to_a * '|'}):\s/, # [[Foo]] :anchor => /^\[\[([^\s\[\]]+)\]\]$/, # Foowhatevs [[Bar]] :anchor_embedded => /^(.*?)\s*\[\[([^\[\]]+)\]\]$/, # [[ref]] (anywhere inline) :anchor_macro => /\\?\[\[([\w":].*?)\]\]/, # matches any unbounded block delimiter: # listing, literal, example, sidebar, quote, passthrough, table, fenced code # does not include open block or air quotes # TIP position the most common blocks towards the front of the pattern :any_blk => %r{^(?:(?:-|\.|=|\*|_|\+|/){4,}|[\|,;!]={3,}|(?:`|~){3,}.*)$}, # detect a list item of any sort # [[:graph:]] is a non-blank character :any_list => /^(?: <?\d+>[[:blank:]]+[[:graph:]]| [[:blank:]]*(?:(?:-|\*|\.){1,5}|\d+\.|[A-Za-z]\.|[IVXivx]+\))[[:blank:]]+[[:graph:]]| [[:blank:]]*.*?(?::{2,4}|;;)(?:[[:blank:]]+[[:graph:]]|$) )/x, # :foo: bar # :Author: Dan # :numbered!: :attr_entry => /^:(\w.*?):(?:[[:blank:]]+(.*))?$/, # {name?value} :attr_conditional => /^\s*\{([^\?]+)\?\s*([^\}]+)\s*\}/, # + Attribute values treat lines ending with ' +' as a continuation, # not a line-break as elsewhere in the document, where this is # a forced line break. This should be the same regexp as :line_break, # below, but it gets its own entry because readability ftw, even # though repeating regexps ftl. :attr_continue => /^[[:blank:]]*(.*)[[:blank:]]\+[[:blank:]]*$/, # :foo!: :attr_delete => /^:([^:]+)!:$/, # An attribute list above a block element # # Can be strictly positional: # [quote, Adam Smith, Wealth of Nations] # Or can have name/value pairs # [NOTE, caption="Good to know"] # Can be defined by an attribute # [{lead}] :blk_attr_list => /^\[(|[[:blank:]]*[\w\{,.#"'].*)\]$/, # block attribute list or block id (bulk query) :attr_line => /^\[(|[[:blank:]]*[\w\{,.#"'].*|\[[^\[\]]*\])\]$/, # attribute reference # {foo} # {counter:pcount:1} :attr_ref => /(\\)?\{((set|counter2?):.+?|\w+(?:[\-]\w+)*)(\\)?\}/, # The author info line the appears immediately following the document title # John Doe <john@anonymous.com> :author_info => /^(\w[\w\-'.]*)(?: +(\w[\w\-'.]*))?(?: +(\w[\w\-'.]*))?(?: +<([^>]+)>)?$/, # [[[Foo]]] (anywhere inline) :biblio_macro => /\\?\[\[\[([\w:][\w:.-]*?)\]\]\]/, # callout reference inside literal text # <1> # special characters will already be replaced, hence their use in the regex :callout_render => /\\?&lt;(\d+)&gt;/, # ...but not while scanning :callout_scan => /\\?<(\d+)>/, # <1> Foo :colist => /^<?(\d+)>[[:blank:]]+(.*)/, # //// # comment block # //// :comment_blk => %r{^/{4,}$}, # // (and then whatever) :comment => %r{^//(?:[^/]|$)}, # one,two;three;four :ssv_or_csv_delim => /,|;/, # one two three :space_delim => /([^\\])[[:blank:]]+/, # Ctrl + Alt+T # Ctrl,T :kbd_delim => /(?:\+|,)(?=[[:blank:]]*[^\1])/, # one\ two\ three :escaped_space => /\\([[:blank:]])/, # 29 :digits => /^\d+$/, # foo:: || foo::: || foo:::: || foo;; # Should be followed by a definition, on the same line... # foo:: That which precedes 'bar' (see also, <<bar>>) # ...or on a separate line # foo:: # That which precedes 'bar' (see also, <<bar>>) # The term may be an attribute reference # {term_foo}:: {def_foo} # REVIEW leading space has already been stripped, so may not need in regex :dlist => /^[[:blank:]]*(.*?)(:{2,4}|;;)(?:[[:blank:]]+(.*))?$/, :dlist_siblings => { # (?:.*?[^:])? - a non-capturing group which grabs longest sequence of characters that doesn't end w/ colon '::' => /^[[:blank:]]*((?:.*[^:])?)(::)(?:[[:blank:]]+(.*))?$/, ':::' => /^[[:blank:]]*((?:.*[^:])?)(:::)(?:[[:blank:]]+(.*))?$/, '::::' => /^[[:blank:]]*((?:.*[^:])?)(::::)(?:[[:blank:]]+(.*))?$/, ';;' => /^[[:blank:]]*(.*)(;;)(?:[[:blank:]]+(.*))?$/   The following pattern, which appears frequently, captures the contents between square brackets, ignoring escaped closing brackets (closing brackets prefixed with a backslash ’\’ character)

Pattern: (?:\[((?:\\]|[^\]])*?)\]) Matches:

enclosed text here
or [enclosed [text\] here]
INTRINSICS = Hash.new{|h,k| STDERR.puts "Missing intrinsic: #{k.inspect}";
SPECIAL_CHARS = { '<' => '&lt;', '>' => '&gt;', '&' => '&amp;'
SPECIAL_CHARS_PATTERN = /[#{SPECIAL_CHARS.keys.join}]/
QUOTE_SUBS = [ # **strong** [:strong, :unconstrained, /\\?(?:\[([^\]]+?)\])?\*\*(.+?)\*\*/m], # *strong* [:strong, :constrained, /(^|[^\w;:}])(?:\[([^\]]+?)\])?\*(\S|\S.*?\S)\*(?=\W|$)/m], # ``double-quoted'' [:double, :constrained, /(^|[^\w;:}])(?:\[([^\]]+?)\])?``(\S|\S.*?\S)''(?=\W|$)/m], # 'emphasis' [:emphasis, :constrained, /(^|[^\w;:}])(?:\[([^\]]+?)\])?'(\S|\S.*?\S)'(?=\W|$)/m], # `single-quoted' [:single, :constrained, /(^|[^\w;:}])(?:\[([^\]]+?)\])?`(\S|\S.*?\S)'(?=\W|$)/m], # ++monospaced++ [:monospaced, :unconstrained, /\\?(?:\[([^\]]+?)\])?\+\+(.+?)\+\+/m], # +monospaced+ [:monospaced, :constrained, /(^|[^\w;:}])(?:\[([^\]]+?)\])?\+(\S|\S.*?\S)\+(?=\W|$)/m], # __emphasis__ [:emphasis, :unconstrained, /\\?(?:\[([^\]]+?)\])?\_\_(.+?)\_\_/m], # _emphasis_ [:emphasis, :constrained, /(^|[^\w;:}])(?:\[([^\]]+?)\])?_(\S|\S.*?\S)_(?=\W|$)/m], # ##unquoted## [:none, :unconstrained, /\\?(?:\[([^\]]+?)\])?##(.+?)##/m], # #unquoted# [:none, :constrained, /(^|[^\w;:}])(?:\[([^\]]+?)\])?#(\S|\S.*?\S)#(?=\W|$)/m], # ^superscript^ [:superscript, :unconstrained, /\\?(?:\[([^\]]+?)\])?\^(.+?)\^/m], # ~subscript~ [:subscript, :unconstrained, /\\?(?:\[([^\]]+?)\])?\~(.+?)\~/m]  
unconstrained quotes:can appear anywhere
constrained quotes:must be bordered by non-word characters
NOTE these substituions are processed in the order they appear here and the order in which they are replaced is important
REPLACEMENTS = [ # (C) [/\\?\(C\)/, '&#169;', :none], # (R) [/\\?\(R\)/, '&#174;', :none], # (TM) [/\\?\(TM\)/, '&#8482;', :none], # foo -- bar [/(^|\n| |\\)--( |\n|$)/, '&#8201;&#8212;&#8201;', :none], # foo--bar [/(\w)\\?--(?=\w)/, '&#8212;', :leading], # ellipsis [/\\?\.\.\./, '&#8230;', :leading], # single quotes [/(\w)\\?'(\w)/, '&#8217;', :bounding], # right arrow -> [/\\?-&gt;/, '&#8594;', :none], # right double arrow => [/\\?=&gt;/, '&#8658;', :none], # left arrow <- [/\\?&lt;-/, '&#8592;', :none], # right left arrow <= [/\\?&lt;=/, '&#8656;', :none], # restore entities [/\\?(&)amp;((?:[[:alpha:]]+|#[[:digit:]]+|#x[[:alnum:]]+);)/, '', :bounding]   NOTE in Ruby 1.8.7, [^\] does not match start of line, so we need to match it explicitly order is significant
Rows = Struct.new(:head, :foot, :body)
VERSION = '0.1.3'

Public Class methods

Public: Parse the AsciiDoc source input into an Asciidoctor::Document

Accepts input as an IO (or StringIO), String or String Array object. If the input is a File, information about the file is stored in attributes on the Document object.

input - the AsciiDoc source as a IO, String or Array. options - a String, Array or Hash of options to control processing (default: {})

          String and Array values are converted into a Hash.
          See Asciidoctor::Document#initialize for details about options.

block - a callback block for handling include::[] directives

returns the Asciidoctor::Document

Public: Parse the contents of the AsciiDoc source file into an Asciidoctor::Document

Accepts input as an IO, String or String Array object. If the input is a File, information about the file is stored in attributes on the Document.

input - the String AsciiDoc source filename options - a String, Array or Hash of options to control processing (default: {})

          String and Array values are converted into a Hash.
          See Asciidoctor::Document#initialize for details about options.

block - a callback block for handling include::[] directives

returns the Asciidoctor::Document

Public: Parse the AsciiDoc source input into an Asciidoctor::Document and render it to the specified backend format

Accepts input as an IO, String or String Array object. If the input is a File, information about the file is stored in attributes on the Document.

If the :in_place option is true, and the input is a File, the output is written to a file adjacent to the input file, having an extension that corresponds to the backend format. Otherwise, if the :to_file option is specified, the file is written to that file. If :to_file is not an absolute path, it is resolved relative to :to_dir, if given, otherwise the Document#base_dir. If the target directory does not exist, it will not be created unless the :mkdirs option is set to true. If the file cannot be written because the target directory does not exist, or because it falls outside of the Document#base_dir in safe mode, an IOError is raised.

If the output is going to be written to a file, the header and footer are rendered unless specified otherwise (writing to a file implies creating a standalone document). Otherwise, the header and footer are not rendered by default and the rendered output is returned.

input - the String AsciiDoc source filename options - a String, Array or Hash of options to control processing (default: {})

          String and Array values are converted into a Hash.
          See Asciidoctor::Document#initialize for details about options.

block - a callback block for handling include::[] directives

returns the Document object if the rendered result String is written to a file, otherwise the rendered result String

Public: Parse the contents of the AsciiDoc source file into an Asciidoctor::Document and render it to the specified backend format

input - the String AsciiDoc source filename options - a String, Array or Hash of options to control processing (default: {})

          String and Array values are converted into a Hash.
          See Asciidoctor::Document#initialize for details about options.

block - a callback block for handling include::[] directives

returns the Document object if the rendered result String is written to a file, otherwise the rendered result String

Public Instance methods

[Validate]