Document the difference between standalone and embeddable output (header_footer documentation)

[graphitefriction]

See the security section for the commented text

[mojavelinux]

Emphasize strongly that the header ends after the first blank line and that document-level attributes (such as toc, toc-title, etc) must be defined in the document header. Several users have been confused when their document-level attribute doesn't work because they are putting a blank line before the attribute entry.

[jaredmorgs]

@mojavelinux please assign this issue to me.

[mojavelinux]

I don't think the topic of this issue is clear, so I will attempt to give it some direction.

We need to document the different between standalone output and embeddable output. This is controlled using the header_footer option (which can only be set from the CLI or API). When the header_footer is enabled, the converter generates a standalone document. When the header_footer is disabled, the converter generates an embeddable document.

Here's how I describe the difference between the two.

The standalone output provides the framing around the content, which includes styling and all the library integrations that the content needs to properly render (e.g., MathJax, the default stylesheet, etc). When you produce an embeddable document, you only get the body content. It's up to you to provide the framing, including the styling and library integrations.

[mojavelinux]

It's also important to note that the default for the header_footer option is circumstance dependent.

• asciidoctor CLI - enabled by default
• asciidoctor API
  • enabled by default if writing to a file (to_file)
  • disabled by default otherwise
• disabled on GitHub and anywhere else the content is being embedded

[mojavelinux]

This information is now covered in these two sections:

• Embedded output
• Standalone output

Arguably, these sections could use a better home. But we can deal with that move in a separate issue.