rearchitect modules and filenames and drop asciidoctor folder under docs

6 files changed, 379 insertions, 0 deletions

diff --git a/docs/modules/api/pages/convert-strings.adoc b/docs/modules/api/pages/convert-strings.adoc
new file mode 100644
index 00000000..1f4a102a
--- /dev/null
+++ b/docs/modules/api/pages/convert-strings.adoc
@@ -0,0 +1,89 @@
+= Load and Convert Strings Using the API
+:navtitle: Load and Convert Strings
+
+To parse an AsciiDoc-formatted string into a document object model, use:
+
+[source,ruby]
+----
+doc = Asciidoctor.load '*This* is Asciidoctor.'
+----
+
+To convert the AsciiDoc-formatted string directly to HTML, use:
+
+[source,ruby]
+----
+puts Asciidoctor.convert '*This* is Asciidoctor.'
+----
+
+Here's the output you will see:
+
+[source,html]
+----
+<div class="paragraph">
+<p><strong>This</strong> is Asciidoctor.</p>
+</div>
+----
+
+When converting a string, Asciidoctor does not output a standalone document by default.
+Instead, it generates embeddable output.
+Let's learn why that is and how to control it.
+
+== Embedded output
+
+When you pass a string to `Asciidoctor.convert` to convert it to a backend format, such as HTML, this method only returns the converted content for those blocks.
+It does not include the frame around that content (i.e., the header and footer) that is needed to make a standalone document.
+Instead, it makes an _embedded_ document.
+This default was chosen to make Asciidoctor consistent with other lightweight markup processors like Markdown.
+
+Here's what's included in an embedded document:
+
+* The document title, but only if the `showtitle` attribute is set (no attribution and revision information)
+* The table of contents if the `toc` attribute is enabled (and not macro or preamble)
+* The converted document body
+* The footnotes unless the `nofootnotes` attribute is set
+
+== Standalone output
+
+You can still generate a standalone document when converting a string.
+To convert from an AsciiDoc string to a standalone output document, you need to explicitly set the `header_footer` option to `true`.
+
+[source,ruby]
+----
+puts Asciidoctor.convert '*This* is Asciidoctor.', header_footer: true
+----
+
+Now you will see a full HTML file.
+
+When the input or output is a file, the `header_footer` option is enabled by default.
+
+[source,ruby]
+----
+Asciidoctor.convert '*This* is Asciidoctor.', to_file: 'out.html'
+----
+
+If you want to generate embedded output when starting with a file, set the `header_footer` option to `false`.
+However, most of the time you'll want to generate a standalone document when converting a file (which is why it's default).
+
+When converting a string, the TOC is only included by default when using the `header_footer` option as shown above (whether it's enabled implicitly or explicitly).
+However, you can force it to be included without the header and footer by setting the `toc` attribute with a value of `macro` and using the `toc::[]` macro in the string itself.
+
+== Convert inline markup only
+
+If you only want the inline markup to be returned, set the `:doctype` option to `'inline'`:
+
+[source,ruby]
+----
+puts Asciidoctor.convert '*This* is Asciidoctor.', :doctype => 'inline'
+----
+
+In this mode, Asciidoctor will only process the first block (e.g., paragraph) in the document and ignore the rest.
+
+== Convert to DocBook
+
+You can produce DocBook 5.0 by setting the `backend` option to `'docbook'`.
+Since embeddable DocBook isn't that useful, we also enable the standalone document (i.e., header and footer) by setting the `header_footer` option to `true`.
+
+[source,ruby]
+----
+puts Asciidoctor.convert '*This* is Asciidoctor.', header_footer: true, backend: 'docbook'
+----
diff --git a/docs/modules/api/pages/generate-html-toc.adoc b/docs/modules/api/pages/generate-html-toc.adoc
new file mode 100644
index 00000000..c53a538b
--- /dev/null
+++ b/docs/modules/api/pages/generate-html-toc.adoc
@@ -0,0 +1,33 @@
+= Generate an HTML TOC
+
+Asciidoctor's HTML 5 converter has built-in support for generating a TOC.
+This TOC generator can also be used as a general purpose API.
+This logic is available via the `outline` method on the HTML5 converter.
+
+The `outline` method excepts a Document object and an optional Hash of options, and returns an HTML string.
+It can be resolved and invoked from anywhere using the following:
+
+[source,ruby]
+----
+html_toc = (Asciidoctor::Converter.for 'html5').outline document
+----
+
+The method can also be executed from inside a converter template (e.g., Slim, Haml, or ERB).
+When using a composite converter, this call will be run through the converter chain.
+
+[source,ruby]
+----
+= converter.convert document, 'outline'
+----
+
+The method is also available through the Document API:
+
+[source,ruby]
+----
+html_doc = document.converter.convert document, 'outline'
+----
+
+The `outline` method accepts the following options:
+
+sectnumlevels:: the number of section levels to number (defaults to the value of the `sectnumlevels` attribute.
+toclevels:: the depth of the toc (defaults to the value of the `toclevels` attribute)
diff --git a/docs/modules/api/pages/index.adoc b/docs/modules/api/pages/index.adoc
new file mode 100644
index 00000000..5c909faa
--- /dev/null
+++ b/docs/modules/api/pages/index.adoc
@@ -0,0 +1,50 @@
+= Process AsciiDoc Using the API
+:url-api: https://www.rubydoc.info/gems/asciidoctor
+////
+API introduction for Asciidoctor
+included in the user-manual Quickstarts, Using the Ruby API
+doc-asciidoctorj is now url-asciidoctorj-docs but! that means I need to fix docref: link:/docs and doc-asciidoctorj: {docref}/asciidoctorj
+////
+
+In addition to its CLI, Asciidoctor provides a Ruby API.
+The API is intended for integration with other software projects and is suitable for server-side applications, such as Rails, Sinatra and GitHub.
+
+Asciidoctor also has a Java API that mirrors the Ruby API.
+The Java API calls through to the Ruby API using an embedded JRuby runtime.
+See the AsciidoctorJ documentation for more information.
+
+== Load and convert a document using the API
+
+To use Asciidoctor in your application, you first need to require the gem:
+
+[source,ruby]
+require 'asciidoctor'
+
+This one statement makes all of the {url-api}[public APIs in Asciidoctor] available to your script or application.
+Now you can start processing AsciiDoc documents.
+The main entry points in the Asciidoctor API are the static methods to load or convert AsciiDoc documents, which we'll cover on this page.
+
+To parse a file into an `Asciidoctor::Document` object:
+
+[source,ruby]
+doc = Asciidoctor.load_file 'my-sample.adoc'
+
+You can get information about the document:
+
+[source,ruby]
+puts doc.doctitle
+puts doc.attributes
+
+To convert a file containing AsciiDoc markup to HTML 5, use:
+
+[source,ruby]
+Asciidoctor.convert_file 'my-sample.adoc'
+
+The command will output to the file [.path]_my-sample.html_ in the same directory.
+
+You can convert the file to DocBook 5.0 by setting the `:backend` option to `'docbook'`:
+
+[source,ruby]
+Asciidoctor.convert_file 'my-sample.adoc', backend: 'docbook'
+
+The command will output to the file [.path]_my-sample.xml_ in the same directory.
diff --git a/docs/modules/api/pages/load-templates.adoc b/docs/modules/api/pages/load-templates.adoc
new file mode 100644
index 00000000..487ecd57
--- /dev/null
+++ b/docs/modules/api/pages/load-templates.adoc
@@ -0,0 +1,24 @@
+= Load Custom Templates
+:url-tilt: https://github.com/rtomayko/tilt
+:url-tests: {url-org}/asciidoctor/tree/master/test
+
+Asciidoctor allows you to override the converter methods used to convert almost any individual AsciiDoc element.
+If you provide a directory of {url-tilt}[Tilt^]-compatible templates, named in such a way that Asciidoctor can figure out which template goes with which element, Asciidoctor will use the templates in this directory instead of its built-in templates for any elements for which it finds a matching template.
+It will fallback to its default templates for everything else.
+
+[source,ruby]
+----
+puts Asciidoctor.convert '*This* is Asciidoctor.', :header_footer => true,
+  :template_dir => 'templates'
+----
+
+The Document and Section templates should begin with `document` and `section`, respectively.
+The file extension is used by Tilt to determine which view framework it will use to use to interpret the template.
+For instance, if you want to write the template in ERB, you'd name these two templates `document.html.erb` and `section.html.erb`.
+The first file extension, `.html`, maps to the converter and the second, `.erb` maps to the template engine.
+To use Haml as the template engine, you'd name the templates `document.html.haml` and `section.html.haml`.
+
+Templates for block elements, like a paragraph or sidebar, are named after the block they handle.
+For instance, to override the default paragraph template with an ERB template, put a file named `paragraph.html.erb` in the template directory you pass to the `Document` constructor using the `:template_dir` option.
+
+For more usage examples, see the {url-tests}[test suite^].
diff --git a/docs/modules/api/pages/options.adoc b/docs/modules/api/pages/options.adoc
new file mode 100644
index 00000000..5a498567
--- /dev/null
+++ b/docs/modules/api/pages/options.adoc
@@ -0,0 +1,165 @@
+= API Options
+
+[cols="15m,15,15,15,15"]
+|===
+|Name |Description |Default value |Allowed values |CLI equivalent
+
+|:attributes
+|Sets additional document attributes, which override equivalently-named attributes defined in the document unless the name or value ends with `@`.
+When using the Hash form, a `nil` value unsets the attribute and a `false` value soft unsets the attribute.
+|_not set_
+|Any number of #builtin-attributes,built-in# or user-defined attributes in one of the following formats:
+
+Hash: +
+`{'name'\=>'value'}` +
+Array: +
+`['name=value']` +
+String: +
+`'name=value'`
+|`-a`, `--attributes`
+
+|:backend
+|Selects the converter to use (as registered with this keyword).
+|html5
+|html5, docbook5, manpage, or any backend registered through an active converter
+|`-b`, `--backend`
+
+|:base_dir
+|Sets the base (aka working) directory containing the document and resources.
+|The directory of the source file, or the working directory if the source is read from a stream.
+|file path
+|`-B`, `--base-dir`
+
+|:catalog_assets
+|If true, tells the parser to capture images and links in the reference table.
+(Normally only IDs, footnotes and indexterms are included).
+The reference table is available via the `references` property on the `document` AST object.
+//NOTE: This is still a primitive and experimental feature.
+//It is intended for early adopters to address special use cases.
+_(Experimental)._
+|false
+|_boolean_
+|_n/a_
+
+|:converter
+|Specifies a user-supplied `Asciidoctor::Converter` instance, used in place of the converter that is automatically resolved from the backend value.
+|_not set_
+|`Asciidoctor::Converter` instance
+|_n/a_
+_(Can be emulated using a combination of `-r` and `-b`)._
+
+|:doctype
+|Sets the document type.
+|article
+|article, book, manpage, inline
+|`-d`, `--doctype`
+
+|:eruby
+|Specifies the eRuby implementation to use for executing the converter templates written in ERB.
+|erb
+|erb, erubis
+|`-e`, `--eruby`
+
+|:extensions
+|A Ruby block that registers (and possibly defines) xref:extensions:register.adoc[Asciidoctor extensions] for this instance of the processor.
+|_not set_
+|A Ruby block that conforms to the Asciidoctor extensions API (the same code that would be passed to the `Extensions.register` method).
+|_n/a_
+_(Can be emulated using `-r`)._
+
+|:extensions_registry
+|Overrides the xref:extensions:register.adoc[extensions registry] instance.
+Instead of providing a Ruby block containing extensions to register, this option lets you replace the extension registry itself, giving you complete control over how extensions are registered for this processor.
+|_not set_
+|`Extensions::Registry` instance
+|_n/a_
+
+|:header_footer
+|If true, add the document header and footer (i.e., framing) around the body content in the output.
+NOTE: The default value for this option is opposite of the default value for the CLI.
+|false
+|_boolean_
+|`-s`, `--no-header-footer`
+
+|:mkdirs
+|If true, the processor will create the necessary output directories if they don't yet exist.
+|false
+|_boolean_
+|_n/a_
+_(Implicitly enabled)._
+
+|:parse
+|If true, the source is parsed eagerly (i.e., as soon as the source is passed to the `load` or `load_file` API).
+If false, parsing is deferred until the `parse` method is explicitly invoked.
+|true
+|_boolean_
+|_n/a_
+
+|:safe
+|Sets the xref:ROOT:safe-modes.adoc[safe mode].
+|:secure
+|:unsafe, :safe, :server, :secure
+|`-S`, `--safe-mode`
+
+|:sourcemap
+|Keeps track of the file and line number for each parsed block.
+(Useful for tooling applications where the association between the converted output and the source file is important).
+|false
+|_boolean_
+|_n/a_
+
+|:template_cache
+|If true, enables the built-in cache used by the template converter when reading the source of template files.
+Only relevant if the `:template_dirs` option is specified.
+|true
+|_boolean_
+|_n/a_
+
+|:template_dir
+|Specifies a directory of Tilt-compatible templates to be used instead of the default built-in templates.
+*Deprecated. Please use `:template_dirs` instead.*
+|_not set_
+|file path
+|`-T`, `--template-dir`
+
+|:template_dirs
+|An array of directories containing Tilt-compatible converter templates to be used instead of the default built-in templates.
+|_not set_
+|An array of file paths
+|`-T`, `--template-dir`
+
+|:template_engine
+|Template engine to use for the custom converter templates.
+The gem with the same name as the engine will be loaded automatically.
+This name is also used to build the full path to the custom converter templates.
+|_auto_ +
+(Set based on the file extension of the custom converter templates found).
+|Template engine name (e.g., slim, haml, erb, etc.)
+|`-E`, `--template-engine`
+
+|:template_engine_options
+|Low-level options passed directly to the template engine.
+//(You can see an example in the Bespoke.js converter at https://github.com/asciidoctor/asciidoctor-bespoke/blob/v1.0.0.alpha.1/lib/asciidoctor-bespoke/converter.rb#L24-L28).
+|_not set_
+|A nested Hash of options with the template engine name as the top-level key and the option name as the second-level key.
+|_n/a_
+
+|:timings
+|Capture time taken to read, parse, and convert document.
+*Internal use only.*
+|_not set_
+|`Asciidoctor::Timings` instance
+|`-t`, `--timings`
+
+|:to_file
+|The name of the output file to write, or true to use the default output file (`docname` + `outfilesuffix`).
+|_not set_
+|true, file path
+|`-o`, `--out-file`
+
+|:to_dir
+|Destination directory for output file(s), relative to `base_dir`.
+|The directory containing the source file, or the working directory if the source is read from a stream.
+|file path
+|`-D`, `--destination-dir`
+|===
diff --git a/docs/modules/api/pages/set-safe-mode.adoc b/docs/modules/api/pages/set-safe-mode.adoc
new file mode 100644
index 00000000..dcf13af6
--- /dev/null
+++ b/docs/modules/api/pages/set-safe-mode.adoc
@@ -0,0 +1,18 @@
+= Set the Safe Mode Using the API
+:navtitle: Set Safe Mode
+
+The default xref:ROOT:safe-modes.adoc[safe mode] in the API is `SECURE`.
+You can change the safe mode using a string, symbol or integer value.
+The value must be set in the document constructor using the `:safe` option.
+
+ result = Asciidoctor.convert_file('master.adoc', :safe => 'server')
+
+or
+
+ result = Asciidoctor.convert_file('master.adoc', :safe => :server)
+
+or
+
+ result = Asciidoctor.convert_file('master.adoc', :safe => 10)
+
+You can also set the xref:cli:set-safe-mode.adoc[safe mode from the CLI] and xref:ROOT:attributes-and-safe-modes.adoc[manage attributes by safe mode].