= Load and Convert Strings Using the API
:navtitle: Load and Convert Strings

This page explains how to load and convert AsciiDoc strings using the API.
A string is the bare AsciiDoc content (often the contents of a file).

== Load an AsciiDoc string

To parse an AsciiDoc string into a document object model, use:

[,ruby]
----
doc = Asciidoctor.load '*This* is Asciidoctor.'
----

You can also read AsciiDoc from a file and pass it to the `load` method:

[,ruby]
----
asciidoc = File.read 'document.adoc', mode: 'r:utf-8'
doc = Asciidoctor.load asciidoc, safe: :safe
----

Once you have loaded the document, you can convert it by calling the convert method:

[,ruby]
-----
doc.convert
-----

However, if you're only interested in converting the AsciiDoc source when using the API, then it's better to use a convert entrypoint.

== Convert an AsciiDoc string

To convert the AsciiDoc string directly to HTML, use:

[,ruby]
----
puts Asciidoctor.convert '*This* is Asciidoctor.'
----

Here's the output you will see:

[,html]
----
<div class="paragraph">
<p><strong>This</strong> is Asciidoctor.</p>
</div>
----

You can also read AsciiDoc from a file and pass it to the `convert` method:

[,ruby]
----
asciidoc = File.read 'document.adoc', mode: 'r:utf-8'
html = Asciidoctor.convert asciidoc, safe: :safe
----

When converting a string, Asciidoctor _does not_ output a standalone document by default.
Instead, it generates embedded output.
Let's learn why that is and how to control it.

== Embedded output

When you pass an AsciiDoc string to `Asciidoctor.convert` to convert it to a backend format, such as HTML, the `:standalone` option is `false` by default.
That means this method only returns the converted content.
This content does not include the frame around that content (i.e., the header and footer) that's included in a standalone document.
In other words, 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 if the `showtitle` attribute is set
* The table of contents if the `toc` attribute is set and the value is not `preamble`
* The converted document body
* The footnotes unless the `nofootnotes` attribute is set

The author and revision information is never shown in an embedded document.
If you need to display that information, you can use attribute references such as `\{author}` and `\{revnumber}`.

The embedded document is intended to be included in a template, such as one provided by a static site generator.
That template is responsible for providing the styles and library integrations needed for the content to render properly.

== 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`.

[,ruby]
----
puts Asciidoctor.convert '*This* is Asciidoctor.', standalone: true
----

Now you'll get a complete HTML file.
The standalone output provides the framing around the content, which includes the styling and all the library integrations the content needs to properly render (e.g., the default stylesheet, MathJax, etc.).
If you don't set the `:standalone` option to `true`, you only get the embedded document (i.e., body content).

When the input or output is a file, the `:standalone` option is enabled by default.
Thus, to instruct Asciidoctor to write standalone HTML to a file from an AsciiDoc string, the `:to_file` option is mandatory. 

[,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'`:

[,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 embedded DocBook isn't that useful, we also enable the standalone document (i.e., header and footer) by setting the `:standalone` option to `true`.

[,ruby]
----
puts Asciidoctor.convert '*This* is Asciidoctor.', standalone: true, backend: 'docbook'
----