diff options
Diffstat (limited to 'docs/modules/html-backend')
16 files changed, 503 insertions, 0 deletions
diff --git a/docs/modules/html-backend/examples/mysample-data-uri.adoc b/docs/modules/html-backend/examples/mysample-data-uri.adoc new file mode 100644 index 00000000..ec32d03e --- /dev/null +++ b/docs/modules/html-backend/examples/mysample-data-uri.adoc @@ -0,0 +1,17 @@ += My First Experience with the Dangers of Documentation +:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger +:imagesdir: myimages +:data-uri: + +In my world, we don't have to worry about mutant, script-injecting warlocks. +No. +We have something far worse. +We're plagued by Wolpertingers. + +== Origins + +[.left.text-center] +image::wolpertinger.jpg[Wolpertinger] + +You may not be familiar with these {url-wolpertinger}[ravenous beasts], +but, trust me, they'll eat your shorts and suck the loops from your code. diff --git a/docs/modules/html-backend/examples/mysample-link.adoc b/docs/modules/html-backend/examples/mysample-link.adoc new file mode 100644 index 00000000..e24aeea9 --- /dev/null +++ b/docs/modules/html-backend/examples/mysample-link.adoc @@ -0,0 +1,13 @@ += My First Experience with the Dangers of Documentation +:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger +:linkcss: + +In my world, we don't have to worry about mutant, script-injecting warlocks. +No. +We have something far worse. +We're plagued by Wolpertingers. + +== Origins + +You may not be familiar with these {url-wolpertinger}[ravenous beasts], +but, trust me, they'll eat your shorts and suck the loops from your code. diff --git a/docs/modules/html-backend/examples/mysample-stylesdir-link.adoc b/docs/modules/html-backend/examples/mysample-stylesdir-link.adoc new file mode 100644 index 00000000..bb56b9e2 --- /dev/null +++ b/docs/modules/html-backend/examples/mysample-stylesdir-link.adoc @@ -0,0 +1,15 @@ += My First Experience with the Dangers of Documentation +:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger +:stylesdir: mystylesheets/ +:stylesheet: mystyles.css +:linkcss: + +In my world, we don't have to worry about mutant, script-injecting warlocks. +No. +We have something far worse. +We're plagued by Wolpertingers. + +== Origins + +You may not be familiar with these {url-wolpertinger}[ravenous beasts], +but, trust me, they'll eat your shorts and suck the loops from your code. diff --git a/docs/modules/html-backend/examples/mysample-stylesdir.adoc b/docs/modules/html-backend/examples/mysample-stylesdir.adoc new file mode 100644 index 00000000..452e7f5c --- /dev/null +++ b/docs/modules/html-backend/examples/mysample-stylesdir.adoc @@ -0,0 +1,14 @@ += My First Experience with the Dangers of Documentation +:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger +:stylesdir: mystylesheets/ +:stylesheet: mystyles.css + +In my world, we don't have to worry about mutant, script-injecting warlocks. +No. +We have something far worse. +We're plagued by Wolpertingers. + +== Origins + +You may not be familiar with these {url-wolpertinger}[ravenous beasts], +but, trust me, they'll eat your shorts and suck the loops from your code. diff --git a/docs/modules/html-backend/examples/mysample-stylesheet.adoc b/docs/modules/html-backend/examples/mysample-stylesheet.adoc new file mode 100644 index 00000000..b1cc475c --- /dev/null +++ b/docs/modules/html-backend/examples/mysample-stylesheet.adoc @@ -0,0 +1,13 @@ += My First Experience with the Dangers of Documentation +:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger +:stylesheet: mystyles.css + +In my world, we don't have to worry about mutant, script-injecting warlocks. +No. +We have something far worse. +We're plagued by Wolpertingers. + +== Origins + +You may not be familiar with these {url-wolpertinger}[ravenous beasts], +but, trust me, they'll eat your shorts and suck the loops from your code. diff --git a/docs/modules/html-backend/examples/mysample.adoc b/docs/modules/html-backend/examples/mysample.adoc new file mode 100644 index 00000000..0a00ca64 --- /dev/null +++ b/docs/modules/html-backend/examples/mysample.adoc @@ -0,0 +1,12 @@ += My First Experience with the Dangers of Documentation +:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger + +In my world, we don't have to worry about mutant, script-injecting warlocks. +No. +We have something far worse. +We're plagued by Wolpertingers. + +== Origins + +You may not be familiar with these {url-wolpertinger}[ravenous beasts], +but, trust me, they'll eat your shorts and suck the loops from your code. diff --git a/docs/modules/html-backend/examples/wrap.adoc b/docs/modules/html-backend/examples/wrap.adoc new file mode 100644 index 00000000..3f877d7d --- /dev/null +++ b/docs/modules/html-backend/examples/wrap.adoc @@ -0,0 +1,17 @@ +// tag::nowrap[] +[source%nowrap,java] +---- +public class ApplicationConfigurationProvider extends HttpConfigurationProvider +{ + @Override + public Configuration getConfiguration(ServletContext context) + { + return ConfigurationBuilder.begin() + .addRule() + .when(Direction.isInbound().and(Path.matches("/{path}"))) + .perform(Log.message(Level.INFO, "Client requested path: {path}")) + .where("path").matches(".*"); + } +} +---- +// end::nowrap[] diff --git a/docs/modules/html-backend/nav.adoc b/docs/modules/html-backend/nav.adoc new file mode 100644 index 00000000..aa1054cb --- /dev/null +++ b/docs/modules/html-backend/nav.adoc @@ -0,0 +1,9 @@ +* xref:index.adoc[] +** xref:manage-stylesheets.adoc[] +** xref:apply-code-stylesheets.adoc[] +** xref:apply-stylesheet.adoc[] +** xref:favicon.adoc[] +** xref:manage-images.adoc[] +** xref:favicon.adoc[] +** xref:verbatim-line-wrap.adoc[] +** xref:skip-front-matter.adoc[] diff --git a/docs/modules/html-backend/pages/apply-code-stylesheets.adoc b/docs/modules/html-backend/pages/apply-code-stylesheets.adoc new file mode 100644 index 00000000..42be39cb --- /dev/null +++ b/docs/modules/html-backend/pages/apply-code-stylesheets.adoc @@ -0,0 +1,27 @@ += Apply CodeRay or Pygments Stylesheets +// um anchor: hl-css +// html-code-styles.adoc, included in convert-documents and the user-manual. + +Asciidoctor can embed the stylesheet for the CodeRay or Pygments syntax highlighters. + +== Requirements + +First, make sure the appropriate library is installed on your system. +See xref:integrations:rouge.adoc[], xref:integrations:coderay.adoc[], or xref:integrations:pygments.adoc[] for installation instructions. +Next, set the xref:asciidoc:verbatim:source-highlighter.adoc[source-highlighter attribute] and assign it the value that corresponds to the library you installed. + +[#coderay] +== CodeRay + +If the `source-highlighter` attribute is `coderay` and the `coderay-css` attribute is `class`, the CodeRay stylesheet is: + +* _embedded_ by default +* _copied_ to the file [.path]_asciidoctor-coderay.css_ inside the `stylesdir` folder within the output directory if `linkcss` is set + +[#pygments] +== Pygments + +If the `source-highlighter` attribute is `pygments` and the `pygments-css` attribute is `class`, the Pygments stylesheet is: + +* _embedded_ by default +* _copied_ to the file [.path]_asciidoctor-pygments.css_ inside the `stylesdir` folder within the output directory if `linkcss` is set diff --git a/docs/modules/html-backend/pages/apply-stylesheet.adoc b/docs/modules/html-backend/pages/apply-stylesheet.adoc new file mode 100644 index 00000000..e645e664 --- /dev/null +++ b/docs/modules/html-backend/pages/apply-stylesheet.adoc @@ -0,0 +1,97 @@ += Apply a Custom Stylesheet +//// +apply-theme.adoc, included in: +- user-manual +- produce-custom-themes-using-asciidoctor-stylesheet-factory +//// + +A custom stylesheet can be stored in the same directory as your document or in a separate directory. +Like the default stylesheet, you can have the output document link to your custom stylesheet or embed it. + +If the stylesheet is in the same directory as your document, you can apply it when converting your document to HTML from the CLI. + + $ asciidoctor -a stylesheet=my-styles.css my-sample.adoc + +. Save your custom stylesheet in the same directory as [.path]_my-sample.adoc_ +. Call the `asciidoctor` processor +. Set `-a` (`--attribute`) and `stylesheet` +. Assign the stylesheet file's name to the `stylesheet` attribute +. Enter your document file's name. + +Alternatively, let's set the `stylesheet` attribute in the header of [.path]_my-sample.adoc_. + +[source,asciidoc] +---- +include::example$mysample-stylesheet.adoc[] +---- + +==== +#fix ex# +//image::mysample-stylesheet.png[] +==== + +When your document and the stylesheet are stored in different directories, you need to tell Asciidoctor where to look for the stylesheet in relation to your document. +Asciidoctor uses the relative or absolute path you assign to the `stylesdir` attribute to find the stylesheet. +Let's move [.path]_my-styles.css_ into [.path]_my-documents/my-stylesheets_. +Our AsciiDoc document, [.path]_my-sample.adoc_, is saved in the [.path]_my-documents_ directory. + +[source,asciidoc] +---- +include::example$mysample-stylesdir.adoc[] +---- + +After processing [.path]_my-sample.adoc_, its HTML output ([.path]_my-sample.html_), which includes the embedded [.path]_my-styles.css_ stylesheet, is created in the [.path]_my-documents_ directory. + +==== +#fix ex# +//image::mysample-stylesdir-dir.png[] +==== + +You can also set `stylesdir` in the CLI. + + $ asciidoctor -a stylesdir=my-stylesheets/ -a stylesheet=my-styles.css my-sample.adoc + +If you don't want to embed the [.path]_my-styles.css_ stylesheet into your HTML output, make sure to set `linkcss`. + +[source,asciidoc] +---- +include::example$mysample-stylesdir-link.adoc[] +---- + +After your document is converted, notice that a copy of [.path]_my-styles.css_ was not created in the [.path]_my-documents_ directory. +Unlike when you link to the default Asciidoctor stylesheet, any custom stylesheets you link to are not copied to the directory where your output is saved. + +[#style-nested] +.Stylesheets and processing multiple nested documents +**** +When you are xref:cli:process-multiple-files.adoc[running Asciidoctor once across a nested set of documents], it's currently not possible to specify a single relative path for the `stylesdir` attribute that would work for all of the documents. +This is because the relative depth of the stylesheet's location differs for the documents in the subdirectories. +One way to solve this problem is to maintain the path to `stylesdir` in each document. + +Let's say you have three AsciiDoc documents saved in the following directory structure: + +.... +/my-documents + a.adoc + b.adoc + /my-nested-documents + c.adoc + /my-stylesheets +.... + +For [.path]_a.adoc_ and [.path]_b.adoc_, set `stylesdir` to: + +[source,asciidoc] +---- +:stylesdir: my-stylesheets +---- + +For [.path]_c.adoc_, set `stylesdir` to: + +[source,asciidoc] +---- +:stylesdir: ../my-stylesheets +---- + +If you're serving your documents from a webserver, you can solve this problem by providing an absolute path to the stylesheet. +**** diff --git a/docs/modules/html-backend/pages/favicon.adoc b/docs/modules/html-backend/pages/favicon.adoc new file mode 100644 index 00000000..34a8f15d --- /dev/null +++ b/docs/modules/html-backend/pages/favicon.adoc @@ -0,0 +1,48 @@ += Add a Favicon + +When using Asciidoctor to generate a standalone HTML document (i.e., the `header_footer` option is `true`), you can instruct the processor to include a link to a favicon by setting the favicon attribute in the document header. + +[source,asciidoc] +---- += Document Title +:favicon: +---- + +By default, the processor will add a link reference of type "icon" that refers to a file named _favicon.ico_ (relative to the HTML document): + +[source,html] +---- +<link rel="icon" type="image/x-icon" href="favicon.ico"> +---- + +This reference gets added inside the HTML `<head>` tag (which explains why this feature is not available when generating an embeddable HTML document). + +To modify the name or location of the icon file, simply assign a value to the favicon attribute: + +[source,asciidoc] +---- += Document Title +:favicon: ./images/favicon/favicon.png +---- + +This will now produce the following HTML tag: + +[source,html] +---- +<link rel="icon" type="image/png" href="./images/favicon/favicon.png"> +---- + +Notice the mimetype is automatically set based on the file extension of the image. + +The value of the `iconsdir` attribute is not prepend to the favicon path as it is with icons in the content. +If you want this directory to be included in the favicon path, you must reference it explicitly: + +[source,asciidoc] +---- +:favicon: {iconsdir}/favicon.png +---- + +TIP: If you're converting a set of AsciiDoc files in multiple directories for the purpose of making a website, and the favicon is located in a shared location, you'll likely want to use a forward slash (`/`) at the beginning of the favicon path. + +If you're looking for more control over how the favicon is declared, you should use a xref:ROOT:docinfo.adoc#head[head docinfo file]. +Keep in mind that if you add an icon link in a head docinfo file and also set the favicon attribute, you'll end up with two icon links in the generated HTML document. diff --git a/docs/modules/html-backend/pages/index.adoc b/docs/modules/html-backend/pages/index.adoc new file mode 100644 index 00000000..5c562bdb --- /dev/null +++ b/docs/modules/html-backend/pages/index.adoc @@ -0,0 +1,81 @@ += Generate HTML from AsciiDoc +:navtitle: Generate HTML + +== HTML 5 converter + +Asciidoctor's default output format is HTML. + +`html5`:: HTML 5 markup styled with CSS3. + +== Generate HTML using the html5 converter + +In this section, we'll create a sample document, then process and convert it with Asciidoctor's `html5` converter. + +. Create an AsciiDoc file like the one below +. Save the file as [.path]_my-sample.adoc_ + +[source,asciidoc] +---- +include::example$mysample.adoc[] +---- + +To convert [.path]_my-sample.adoc_ to HTML from the command line: + +. Open a console +. Switch to the directory that contains the [.path]_my-sample.adoc_ document +. Call the Asciidoctor processor with the `asciidoctor` command, followed by the name of the document you want to convert + +//^ + + $ asciidoctor my-sample.adoc + +Remember, Asciidoctor's default converter is html5, so it isn't necessary to specify it with the `-b` command. + +You won't see any messages printed to the console. +If you type `ls` or view the directory in a file manager, there is a new file named [.path]_my-sample.html_. + + $ ls + my-sample.adoc my-sample.html + +Asciidoctor derives the name of the output document from the name of the input document. + +Open [.path]_my-sample.html_ in your web browser. +Your document should look like the image below. + +==== +#fix ex# +//image::mysample.png[] +==== + +The document's text, titles, and link is styled by the default Asciidoctor stylesheet, which is embedded in the HTML output. +As a result, you could save [.path]_my-sample.html_ to any computer and it will look the same. + +[#xhtml] +== Generate XHTML + +To convert AsciiDoc to XHTML, set the backend to `xhtml5`. + +.Produce XHTML using the built-in HTML converter +[source,console] +---- +asciidoctor -b xhtml5 document.adoc +---- + +To produce XHTML instead of HTML when using converter templates, set the `htmlsyntax` attribute to `xml` in addition to the backend option: + +.Produce XHTML using custom templates +[source,console] +---- +asciidoctor -T /path/to/templates -b slides -a htmlsyntax=xml document.adoc +---- + +.Black Box Decoded: XHTML and htmlsyntax +**** +XHTML output is a special mode of the built-in HTML5 converter. +It is activated by prefixing the backend value with `x` (e.g., `xhtml` or `xhtml5`). +This hint implicitly assigns the `htmlsyntax` attribute to the value `xml`, which normally has the value `html`. + +For all other converters, the `htmlsyntax` attribute is not set explicitly. +If you want a converter template that's written in Slim or Haml to output XHTML instead of the default HTML, you simply need to set the `htmlsyntax` attribute to `xml` explicitly. +Asciidoctor will pass on this preference to the Slim or Haml template engine by setting the `:format` option to `:html5`. +**** diff --git a/docs/modules/html-backend/pages/manage-images.adoc b/docs/modules/html-backend/pages/manage-images.adoc new file mode 100644 index 00000000..38b69aae --- /dev/null +++ b/docs/modules/html-backend/pages/manage-images.adoc @@ -0,0 +1,24 @@ += Manage Images + +Images are not embedded in the HTML output by default. +If you have image references in your document, you'll have to save the image files in the same directory as your converted document. + +As an alternative, you can embed the images directly into the document by setting the `data-uri` document attribute. + + $ asciidoctor -a data-uri my-sample.adoc + +[source,asciidoc] +---- +include::example$mysample-data-uri.adoc[] +---- + +==== +#fix ex# +//image::mysample-data-uri.png[] +==== + +If the target of one or more images in the document is a URI, you must also set the `allow-uri-read` attribute securely and run Asciidoctor in `SECURE` mode or less. + + $ asciidoctor -a data-uri -a allow-uri-read my-sample.adoc + +The same is true when converting the document to PDF using Asciidoctor PDF, even if the `allow-uri-read` attribute is not set (since the behavior is implied). diff --git a/docs/modules/html-backend/pages/manage-stylesheets.adoc b/docs/modules/html-backend/pages/manage-stylesheets.adoc new file mode 100644 index 00000000..aa6042b3 --- /dev/null +++ b/docs/modules/html-backend/pages/manage-stylesheets.adoc @@ -0,0 +1,46 @@ += Manage Stylesheets + +== What is the default stylesheet? + +Asciidoctor comes bundled with a stylesheet, named [.path]_asciidoctor.css_. +It uses this stylesheet for HTML document styling and JavaScript for generating document attributes such as a table of contents and footnotes. +This stylesheet is applied by default unless you tell Asciidoctor to use another stylesheet. +See xref:html-backend:apply-stylesheet.adoc[] to learn about the default and custom stylesheet options. + +== Embed a stylesheet + +When you generate a document with the `html5` backend, the [.path]_asciidoctor.css_ stylesheet is embedded into the HTML output by default when the safe mode is less than `SECURE`. +If your stylesheet is being linked to when you expect it to be embedded, lower the safe mode (`safe` is the recommend value). + +== Link to a stylesheet + +You can link to the stylesheet instead of embedding it. +This is the mandatory behavior when the safe mode is `SECURE`. + +To have your document link to the stylesheet, set the `linkcss` attribute in the document's header. + +[source,asciidoc] +---- +include::example$mysample-link.adoc[] +---- + +You can also set `linkcss` with the CLI. + + $ asciidoctor -a linkcss my-sample.adoc + +Now, when you view the directory, you should see the file [.path]_asciidoctor.css_ in addition to [.path]_my-sample.adoc_ and [.path]_my-sample.html_. +The `linkcss` attribute automatically copies [.path]_asciidoctor.css_ to the output directory. +Additionally, you can inspect [.path]_my-sample.html_ in your browser and see `<link rel="stylesheet" href="./asciidoctor.css">` inside the `<head>` tags. + +==== +#fix ex# +//image::mysample-link.png[] +==== + +== Don't apply a stylesheet + +If you don't want any styles applied to the HTML output of your document, unset the `stylesheet` attribute. + + $ asciidoctor -a stylesheet! my-sample.adoc + +One of Asciidoctor's strengths is the ease in which you can swap the default stylesheet for your own xref:apply-stylesheet.adoc[custom stylesheet]. diff --git a/docs/modules/html-backend/pages/skip-front-matter.adoc b/docs/modules/html-backend/pages/skip-front-matter.adoc new file mode 100644 index 00000000..0eb065d5 --- /dev/null +++ b/docs/modules/html-backend/pages/skip-front-matter.adoc @@ -0,0 +1,30 @@ += Skip Front Matter + +== Front matter for static site generators + +Many static site generators (i.e., Jekyll, Middleman) rely on [.term]*front matter* added to the top of the document to determine how to convert the content. +Front matter typically starts on the first line of a file and is bounded by block delimiters (e.g., `+---+`). + +Here's an example of a document that contains front matter: + +[source,asciidoc] +---- +--- <.> +layout: default <.> +--- <.> += Document Title + +content +---- +<.> Front matter opening delimiter +<.> Front matter data +<.> Front matter closing delimiter + +The static site generator removes these lines before passing the document to the AsciiDoc processor to be converted. +Outside of the tool, however, these extra lines can throw off the processor. + +== skip-front-matter option + +If the `skip-front-matter` option is set via the API or CLI (e.g., `-a skip-front-matter`), Asciidoctor will recognize the front matter and consume it before parsing the document. +Asciidoctor stores the content it removes in the `front-matter` attribute to make it available for integrations. +Asciidoctor also removes front matter when reading xref:asciidoc:directives:include.adoc[include files]. diff --git a/docs/modules/html-backend/pages/verbatim-line-wrap.adoc b/docs/modules/html-backend/pages/verbatim-line-wrap.adoc new file mode 100644 index 00000000..f38b7daa --- /dev/null +++ b/docs/modules/html-backend/pages/verbatim-line-wrap.adoc @@ -0,0 +1,40 @@ += Verbatim Block Line Wrapping + +The default Asciidoctor stylesheet wraps long lines in verbatim blocks by applying the CSS `white-space: pre-wrap` and `word-wrap: break-word`. +The lines are wrapped at word boundaries, similar to how most text editors wrap lines. +This prevents horizontal scrolling which some users considered a greater readability problem than line wrapping. + +However, this behavior is configurable because there are times when you don't want the lines in listing and literal blocks to wrap. + +== Prevent line wrapping + +There are two ways to prevent lines from wrapping so that horizontal scrolling is used instead: + +* `nowrap` block option +* unset the `prewrap` document attribute (on by default) + +You can use the `nowrap` option on literal or listing blocks to prevent lines from being wrapped in the HTML. + +// FIXME this section is creating broken AsciiDoc!! +.Listing block with nowrap option syntax +.... +include::example$wrap.adoc[tag=nowrap] +.... + +When the nowrap option is used, the `nowrap` class is added to the `<pre>` element. +This class changes the CSS to `white-space: pre` and `word-wrap: normal`. + +.Result: Listing block with nowrap option applied +include::example$wrap.adoc[tag=nowrap] + +To prevent lines from wrapping globally, unset the `prewrap` attribute on the document. + +.Disable prewrap globally (thus, enabling nowrap) +[source] +---- +:prewrap!: +---- + +When the prewrap attribute is unset, the `nowrap` class is added to any `<pre>` elements. + +Now, you can use the line wrapping strategy that works best for you and your readers. |