diff options
Diffstat (limited to 'docs/modules/api')
| -rw-r--r-- | docs/modules/api/nav.adoc | 6 | ||||
| -rw-r--r-- | docs/modules/api/pages/convert-strings.adoc | 89 | ||||
| -rw-r--r-- | docs/modules/api/pages/generate-html-toc.adoc | 33 | ||||
| -rw-r--r-- | docs/modules/api/pages/index.adoc | 50 | ||||
| -rw-r--r-- | docs/modules/api/pages/load-templates.adoc | 24 | ||||
| -rw-r--r-- | docs/modules/api/pages/options.adoc | 143 | ||||
| -rw-r--r-- | docs/modules/api/pages/set-safe-mode.adoc | 21 |
7 files changed, 366 insertions, 0 deletions
diff --git a/docs/modules/api/nav.adoc b/docs/modules/api/nav.adoc new file mode 100644 index 00000000..25a3a937 --- /dev/null +++ b/docs/modules/api/nav.adoc @@ -0,0 +1,6 @@ +* xref:index.adoc[] +** xref:convert-strings.adoc[] +** xref:generate-html-toc.adoc[] +** xref:load-templates.adoc[] +** xref:set-safe-mode.adoc[] +** xref:options.adoc[] diff --git a/docs/modules/api/pages/convert-strings.adoc b/docs/modules/api/pages/convert-strings.adoc new file mode 100644 index 00000000..71577c74 --- /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 `standalone` option to `true`. + +[source,ruby] +---- +puts Asciidoctor.convert '*This* is Asciidoctor.', standalone: true +---- + +Now you will see a full HTML file. + +When the input or output is a file, the `standalone` 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 `standalone` 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 `standalone` 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 `standalone` option to `true`. + +[source,ruby] +---- +puts Asciidoctor.convert '*This* is Asciidoctor.', standalone: 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..6a53b4b1 --- /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..2f9a16f1 --- /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.', + standalone: 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..c0f30552 --- /dev/null +++ b/docs/modules/api/pages/options.adoc @@ -0,0 +1,143 @@ += API Options + +[cols="~,~,30%,~"] +|=== +|Name |Description |Default value |Allowed values + +|`:attributes` +|Sets document attributes, which override equivalently-named attributes defined in the document unless soft set (`@`). +When using the hash format, a `nil` value unsets the attribute and a `false` value soft unsets the attribute. +|_not set_ +|xref:asciidoc:attributes:document-attributes.adoc[Document attributes] in the following formats: + +Hash: + +`{'name'\=>'value'}` + +Array: + +`['name=value']` + +String: + +`'name=value'` + +|`:backend` +|Selects the converter to use. +|`html5` +|`html5`, `docbook5`, `manpage`, or a backend registered through an active converter + +|`:base_dir` +|Sets the base (aka working) directory containing the document and resources. +|Directory of the source file, or the working directory if the source is read from a stream. +|file path + +|`:catalog_assets` +|If `true`, the parser captures 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_ + +|`: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 + +|`:doctype` +|Sets the document type. +|`article` +|`article`, `book`, `manpage`, `inline` + +|`:eruby` +|Specifies the eRuby implementation to use for executing the converter templates written in ERB. +|`erb` +|`erb`, `erubis` + +|`: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). + +|`: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 + +|`:standalone` +|If `true`, generates a standalone output document (which includes the shell around the body content, such as the header and footer). +When converting to a file, the default value is `true`. +Otherwise, the default value is `false`. +The deprecated alias for this option is `:header_footer`. +The default value for this option is opposite of the default value for the CLI. +|_Varies_ +|_Boolean_ + +|`:mkdirs` +|If `true`, the processor creates the necessary output directories if they don't yet exist. +|`false` +|_Boolean_ + +|`: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_ + +|`:safe` +|Sets the xref:ROOT:safe-modes.adoc[safe mode]. +|`:secure` +|`:unsafe`, `:safe`, `:server`, `:secure` + +|`:sourcemap` +|Tracks 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_ + +|`:template_cache` +|Enables the built-in cache used by the template converter when reading the source of template files. +Only relevant if `:template_dirs` is specified. +|`true` +|_Boolean_ + +//|`:template_dir` +//|Specifies a directory of Tilt-compatible templates to be used instead of the default built-in templates. +//*Deprecated. Use `:template_dirs` instead.* +//|_not set_ +//|file path + +|`:template_dirs` +|Array of directories containing Tilt-compatible converter templates to be used instead of the default built-in templates. +|_not set_ +|Array of file paths + +|`: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.) + +|`: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_ +|Nested Hash of options with the template engine name as the top-level key and the option name as the second-level key. + +|`:timings` +|Capture time taken to read, parse, and convert document. +*Internal use only.* +|_not set_ +|`Asciidoctor::Timings` instance + +|`:to_file` +|Name of the output file to write, or `true` to use the default output file (`docname` + `outfilesuffix`). +|_not set_ +|`true`, file path + +|`:to_dir` +|Destination directory for output file(s), relative to `base_dir`. +|Directory containing source file, or working directory if source is read from a stream. +|File path +|=== 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..eca166a3 --- /dev/null +++ b/docs/modules/api/pages/set-safe-mode.adoc @@ -0,0 +1,21 @@ += 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. + +== Set :safe option + +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:reference-safe-mode.adoc[enable or disable content based on the current safe mode]. |