diff options
Diffstat (limited to 'docs/modules/html-backend')
17 files changed, 819 insertions, 0 deletions
diff --git a/docs/modules/html-backend/examples/my-document.adoc b/docs/modules/html-backend/examples/my-document.adoc new file mode 100644 index 00000000..e2a0abd5 --- /dev/null +++ b/docs/modules/html-backend/examples/my-document.adoc @@ -0,0 +1,19 @@ +// tag::title[] += The Dangers of Wolpertingers +:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger +// end::title[] +// tag::body[] + +Don't worry about gumberoos or splintercats. +Something far more fearsome plagues the days, nights, and inbetweens. +Wolpertingers. + +== Origins + +Wolpertingers are {url-wolpertinger}[ravenous beasts]. +// end::body[] +// tag::image[] +[.left.text-center] +image:wolpertinger.jpg[Wolpertinger,100,,link="https://commons.wikimedia.org/wiki/File:Wolpertinger.jpg"] +They may look cute and cuddly, but don't be fooled. +// end::image[] 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/images/default-stylesheet.png b/docs/modules/html-backend/images/default-stylesheet.png Binary files differnew file mode 100644 index 00000000..4584a510 --- /dev/null +++ b/docs/modules/html-backend/images/default-stylesheet.png diff --git a/docs/modules/html-backend/images/my-document-with-data-uri.png b/docs/modules/html-backend/images/my-document-with-data-uri.png Binary files differnew file mode 100644 index 00000000..dafb8ced --- /dev/null +++ b/docs/modules/html-backend/images/my-document-with-data-uri.png diff --git a/docs/modules/html-backend/images/my-document.png b/docs/modules/html-backend/images/my-document.png Binary files differnew file mode 100644 index 00000000..37b34fc0 --- /dev/null +++ b/docs/modules/html-backend/images/my-document.png diff --git a/docs/modules/html-backend/images/no-stylesheet.png b/docs/modules/html-backend/images/no-stylesheet.png Binary files differnew file mode 100644 index 00000000..ffe779b8 --- /dev/null +++ b/docs/modules/html-backend/images/no-stylesheet.png diff --git a/docs/modules/html-backend/images/wolpertinger.jpg b/docs/modules/html-backend/images/wolpertinger.jpg Binary files differnew file mode 100644 index 00000000..cc2caa21 --- /dev/null +++ b/docs/modules/html-backend/images/wolpertinger.jpg diff --git a/docs/modules/html-backend/nav.adoc b/docs/modules/html-backend/nav.adoc new file mode 100644 index 00000000..e887d6da --- /dev/null +++ b/docs/modules/html-backend/nav.adoc @@ -0,0 +1,10 @@ +* xref:index.adoc[] +** Stylesheets +*** xref:default-stylesheet.adoc[] +*** xref:stylesheet-modes.adoc[] +*** xref:custom-stylesheet.adoc[] +*** xref:source-highlighting-stylesheets.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/custom-stylesheet.adoc b/docs/modules/html-backend/pages/custom-stylesheet.adoc new file mode 100644 index 00000000..18591039 --- /dev/null +++ b/docs/modules/html-backend/pages/custom-stylesheet.adoc @@ -0,0 +1,200 @@ += Apply a Custom Stylesheet + +So far we've talked about different ways of using the default stylesheet. +In place of the default stylesheet, you can instruct Asciidoctor to use a custom stylesheet of your choosing. +On this page, you'll learn how to apply a custom stylesheet and, if necessary, how to get Asciidoctor to copy and link to that stylesheet into the correct location. +You'll also learn about some of the limitations of this feature when processing multiple documents. + +== Specify the custom stylesheet + +Asciidoctor looks for the stylesheet file specified by the `stylesheet` document attribute. +If the value of this attribute is empty (the default), Asciidoctor uses the default stylesheet. +Otherwise, Asciidoctor assumes the value is the path of a custom stylesheet file relative to the source document. +All the same behavior described in xref:stylesheet-modes.adoc[] still applies, except Asciidoctor uses the specified stylesheet instead of the default stylesheet. + +To begin, you must create a stylesheet file. +For now, create this file adjacent to your AsciiDoc document. +To keep it simple, we'll just define a basic stylesheet that changes all text to red. +Create the file [.path]_my-stylesheet.css_ the directory with your AsciiDoc source files and populate it with the following contents: + +.my-stylesheet.css +[source,css] +---- +body { + color: #ff0000; +} +---- + +Now let's use the `stylesheet` attribute to apply it. + +The `stylesheet` document attribute must be set by the end of the header to be effective. +One way to do that is to set the attribute in the document header: + +.stylesheet attribute set in document header +[source,asciidoc] +---- +include::example$my-document.adoc[tag=title] +:stylesheet: my-stylesheet.css +include::example$my-document.adoc[tag=body] +---- + +You can also set `stylesheet` using the API or CLI (shown here): + + $ asciidoctor -a stylesheet=my-stylesheet.css my-document.adoc + +When you view the generated HTML file [.path]_my-document.html_ in your browser, you'll see that all the text is red. + +TIP: If you want to create a custom stylesheet by extending the default stylesheet, see xref:default-stylesheet.adoc#customize-extend[Extend the default stylesheet]. + +As with the default stylesheet, you can set the `linkcss` document attribute and Asciidoctor will link to your stylesheet instead. +(Note that it doesn't copy it in this case since it's already in the same folder as the output file). + + $ asciidoctor -a stylesheet=my-stylesheet.css -a linkcss my-document.adoc + +You may not want to keep your stylesheet in the same directory as your AsciiDoc documents. +Let's see how to tell Asciidoctor to look for it elsewhere. + +== Configure the styles directory + +When your stylesheet is in a directory below your AsciiDoc document, you need to tell Asciidoctor where to look to find the stylesheet. +There are two equivalent ways to do so: + +* Specify the name of the stylesheet file using the `stylesheet` attribute and the directory where it's located using the `stylesdir` attribute +* Include the directory where the stylesheet is located in the value of the `stylesheet` attribute (instead of using the `stylesdir` attribute) + +The value of the `stylesdir` attribute can end with a trailing directory separator (`/`), but it's not required. + +If the `linkcss` attribute is not set, the styles directory can be either relative or absolute. +The situation gets trickier when `linkcss` is set, which we'll <<stylesdir-and-linkcss,get to later>>. + +Let's assume you want to put your stylesheet in the [.path]_my-styles_ folder relative to your AsciiDoc document(s). +Go ahead and create that folder and move your custom stylesheet into it for this example. +Now we need to tell Asciidoctor where it's located using `stylesdir`. + +The `stylesdir` document attribute must be set by the end of the header to be effective. +One way to do that is to set the attribute in the document header: + +.stylesdir attribute set in document header +[source,asciidoc] +---- +include::example$my-document.adoc[tag=title] +:stylesheet: my-stylesheet.css +:stylesdir: my-styles +include::example$my-document.adoc[tag=body] +---- + +You can also set `stylesdir` using the API or CLI (shown here): + + $ asciidoctor -a stylesdir=my-styles -a stylesheet=my-stylesheet.css my-document.adoc + +Asciidoctor now looks for the stylesheet file [.path]_my-styles/my-stylesheet.css_ relative to the AsciiDoc document and embeds it into the HTML. + +You can achieve the same result by including the directory in the value of the `stylesheet` attribute: + + $ asciidoctor -a stylesheet=my-styles/my-stylesheet.css my-document.adoc + +If you set the value of `stylesdir` to an absolute directory, then Asciidoctor would still locate the stylesheet and embed it into the HTML. +But this can create problems if you've configured the converter to link to the stylesheet instead. +Let's look at thoses problem and ways to work through them. + +[#stylesdir-and-linkcss] +== Styles directory and linkcss + +Using `stylesdir` gets tricky when your linking to the stylesheet instead of embedding it. +That's because we're now dealing with two different paths. +One is the path where the stylesheet is located on disk (either absolute or relative to the document). +The other is the path the browser uses to access the stylesheet. + +First, it's important to understand that Asciidoctor mirrors the `stylesdir` path in the link reference. +Let's use the previous example to demonstrate. +If you invoke Asciidoctor as follows: + + $ asciidoctor -a stylesdir=my-styles -a stylesheet=my-stylesheet.css -a linkcss my-document.adoc + +Then when you inspect the HTML, you will see: + +[source,html] +---- +<link rel="stylesheet" href="my-styles/asciidoctor.css"> +---- + +Notice how the value of `stylesdir` ([.path]_my-styles_) is included in the referenced path. +Asciidoctor will also preserve this directory if it needs to copy the stylesheet file. + +There are certain situations where this isn't going to work (at least not when publishing the file to the public internet). +Let's consider one such case. +We'll specify the location of `stylesdir` as an absolute path and generate the output file into a separate output directory. + + $ asciidoctor -a stylesdir=`pwd`/my-styles -a stylesheet=my-stylesheet.css -a linkcss -D public my-document.adoc + +Asciidoctor generates the HTML file into the [.path]_public_ folder, but it does not copy the stylesheet. +Furthermore, it uses an absolute path in the link to the stylesheet: + +[source,html] +---- +<link rel="stylesheet" href="/path/to/documents/my-styles/asciidoctor.css"> +---- + +What we want is for Asciidoctor to copy the stylesheet to the output directory and link to it using a relative path. + +A similar problem comes up if you want to control the styles directory and stylesheet file referenced by the HTML independently of the location where they are taken. + +In brief, we need to be able to decouple the path where the stylesheet is read from the location where the stylesheet is published and referenced. +That's where the `copycss` attribute comes back into play. + +[#copy-link-split] +== Copy from one place, link to another + +For complex combinations that involve `stylesdir`, `linkcss`, and an explicit output directory, the meaning of `stylesdir` is too overloaded and needs to be reconciled. +We can turn to the `copycss` attribute to clear this situation up. + +NOTE: This situation is unique to when `linkcss` is set. +It's not a problem when the converter embeds the stylesheet since there is no secondary reference involved. + +The `copycss` attribute can accepts a value. +Asciidoctor uses that value as an override for where to look for the stylesheet to read. +The converter, on the other hand, does not use this value. +That means we can use `stylesdir` and `stylesheet` to assemble the path relative to the output directory where Asciidoctor should write and link to the stylesheet independent of the location where it reads the file. + +Let's revisit the broken scenario from the previous section and use `copycss` to reconcile the problem: + + $ asciidoctor -a stylesdir=css -a stylesheet=default.css \ + -a copycss=`pwd`/my-styles/my-stylesheet.css -a linkcss -D public my-document.adoc + +Asciidoctor copies the stylesheet from the absolute path specified by the `copycss` attribute to the path [.path]_public/css/default.css_ and links to it using the path [.path]_css/default.css_. +Notice that we even changed the name of the folder and stylesheet file in the output. +That demonstrates that we have decoupled the path where the stylesheet is read from the location where the stylesheet is published and referenced. + +== Styles directory and nested documents when linking + +When xref:cli:process-multiple-files.adoc[invoking Asciidoctor on a nested set of documents], it's currently not possible to specify a single relative path for the `stylesdir` attribute that works 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-styles +.... + +For [.path]_a.adoc_ and [.path]_b.adoc_, set `stylesdir` to: + +[source,asciidoc] +---- +:stylesdir: my-styles +---- + +For [.path]_c.adoc_, set `stylesdir` to: + +[source,asciidoc] +---- +:stylesdir: ../my-styles +---- + +If you're serving your documents from a webserver, you can solve this problem by providing an absolute path to the stylesheet. +You can also try to use the `copycss` per document to control where Asciidoctor looks for the stylesheet independent of where Asciidoctor copies it and the converter configured the HTML to reference it. diff --git a/docs/modules/html-backend/pages/default-stylesheet.adoc b/docs/modules/html-backend/pages/default-stylesheet.adoc new file mode 100644 index 00000000..3b1616ad --- /dev/null +++ b/docs/modules/html-backend/pages/default-stylesheet.adoc @@ -0,0 +1,176 @@ += Default Stylesheet + +When you use the HTML converter to generate a standalone HTML document, Asciidoctor includes a default stylesheet to ensure the HTML it produces look great right out of the box. +This, in turn, gets you up and running quickly by giving you a result to preview or publish without having to do any additional work. + +This page covers why the default is necessary, how to apply it, and how to build on it so you don't have to create a stylesheet from scratch. + +NOTE: The default stylesheet that Asciidoctor provides is just that, _a default_. +If you don't like its appearance, you can customize it or replace it with a different once. +Though, it's important to understand what purpose the stylesheet serves when doing so. + +// TODO: we probably need a page to defines what styles any stylesheet must provide to be fully compatible with AsciiDoc +== Why provide a default? + +As previously stated, a default stylesheet is included to provide a nice out-of-the-box experience. +But there's more to it. +There are elements of AsciiDoc that require stylesheet support. + +One example is to honor *built-in roles*, such as `text-center`. +In order for a role to take effect, it needs a companion CSS class in the stylesheet. +To satisfy the expectations of a built-in role, a stylesheet is required. + +Another example is to implement *list marker styles*. +AsciiDoc allows you to specify the marker for a list using a block style (e.g., `loweralpha`). +However, HTML does not apply these markers by default. +Rather, it's something that the stylesheet provides. + +The default stylesheet also applies *borders and shading to table cells* to support all combinations of the frame, grid, and stripes attributes. + +Yet another example is the *TOC position*. +To position the TOC on the left or right requires help from the stylesheet to change the layout of the page so the TOC appears as a sidebar. +It's the stylesheet that handles that task. + +In order for the AsciiDoc experience to be complete when generating HTML, a stylesheet is required. +The default stylesheet not only completes this experience, but also serves as a reference for the styles a custom stylesheet must provide. + +=== Web fonts + +The default stylesheet ensures that the same fonts are selected across all platforms. + +By default, the browser relies on system fonts. +But system fonts vary widely by platform, so users end up getting a very different experience. +That's where web fonts come in. + +When the default stylesheet is used, the converter adds additional HTML to load open source fonts from Google Fonts. +The default stylesheet, in turn, specifies a preference for these fonts. + +The web fonts used by the default stylesheet are as follows: + +Noto Serif:: body text (default) +Open Sans:: headings +Droid Sans Mono:: monospaced phrases and verbatim blocks + +Loading and preferring these web fonts ensures everyone sees the same result. + +== Usage + +When generating HTML, there's nothing special you need to do to apply the default stylesheet. +Asciidoctor automatically embeds it in the `<head>` of the generated HTML when you run the `asciidoctor` command. + + $ asciidoctor document.adoc + +Since no stylesheet is specified, Asciidoctor uses the stylesheet (located at [.path]_data/stylesheets/asciidoctor.css_ inside the installed gem). +When you view the generated HTML file, [.path]_document.html_, you'll see styled HTML, as shown here: + +image::default-stylesheet.png[] + +When using the API, Asciidoctor links to the stylesheet by default instead of embedding it (due to the safe mode). +Yet, it does not copy the stylesheet to the output directory (it needs to be placed there separately). +If it's not already there, the browser will not be able to find the stylesheet. +To solve this problem, set the safe mode to server or lower (e.g., server, safe, or unsafe) and Asciidoctor will embed the default stylesheet, like when using the `asciidoctor` command. + +[source,ruby] +---- +require 'asciidoctor' + +Asciidoctor.convert_file 'document.adoc', safe: :safe +---- + +== Disable or modify the web fonts + +When the default stylesheet is used, the converter adds a `<link rel="stylesheet">` tag to load web fonts from Google Fonts. +You can disable this link by unsetting the `webfonts` document attribute from the CLI, API, or document header. + + $ asciidoctor -a webfonts! document.adoc + +With the web fonts absent, the browser will drop back to the fallback system fonts specified in the stylesheet. +But this also provides an opportunity to use <<customize-docinfo,docinfo>> to load the web fonts from a different source. + +Rather than disabling the link, you can also use the `webfonts` attribute to change which fonts are loaded. +When set, the value of the `webfonts` attribute is used as the value of the `family` query string parameter in the font-loader URL. + +Let's say you want to use Ubuntu Mono instead of Droid Sans Mono for monospaced text. +You would set the `webfonts` attribute as follows: + + $ asciidoctor \ + -a webfonts="Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CUbuntu+Mono:400" \ + document.adoc + +In this case, you would still need to use <<customize-docinfo,docinfo>> to instruct the stylesheet to use the new font. + +== Customize the default stylesheet + +What if the default stylesheet is not exactly to your liking, but you don't want to go off and create a custom stylesheet from scratch? +Can you customize it? +Indeed, you can. + +There are at least two ways to customize the default stylesheet. +One way is to add auxiliary styles using docinfo. +Another way is to create a custom stylesheet, but import the default stylesheet as a starting point. + +[#customize-docinfo] +=== Auxiliary styles with docinfo + +Adding auxiliary styles is a great use case for xref:ROOT:docinfo.adoc[docinfo]. +The docinfo feature in AsciiDoc allows you to inject auxiliary content from a file into various places in the HTML output. +In this case, we're interested in the "head" position, which injects content at the bottom of the `<head>` tag. + +Let's say you want to change the color of headings (and other heading-like titles) to match the color of paragraph text. +Start by creating a file named [.path]_docinfo.html_ (head is the default location) and populate it with a `<style>` tag with the necessary styles. + +.docinfo.html +[source,html] +---- +<style> +h1, h2, h3, h4, h5, h6, #toctitle, +.sidebarblock > .content > .title { + color: rgba(0, 0, 0, 0.8); +} +</style> +---- + +Now tell Asciidoctor to look for and load the docinfo file using the `docinfo` attribute: + + $ asciidoctor -a docinfo=shared document.adoc + +The `<style>` tag in your docinfo file will be inserted directly below the default stylesheet in the generated HTML. + +[#customize-extend] +=== Extend the default stylesheet + +Instead of writing a custom stylesheet from scratch, you can import the default stylesheet and add overrides for any styles you want to change (leveraging the cascading nature of CSS). +This is also a good way to use the default stylesheet, but load web fonts from a different CDN. + +Let's again change the color of headings (and other heading-like titles) to match the color of paragraph text. +Start by creating a stylesheet named [.path]_my-asciidoctor.css_ and adding an `@import` declaration that references the default stylesheet and the web fonts it uses (which are not included in the source of the default stylesheet). +We'll use a CDN to pull it directly out of the repository, but you can put it anywhere the browser can access it. +Then add your overrides below those declarations. + +[source,css,subs=attributes+] +---- +@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; +@import "https://cdn.jsdelivr.net/gh/asciidoctor/asciidoctor@{page-component-version}/data/stylesheets/asciidoctor-default.css"; + +h1, h2, h3, h4, h5, h6, #toctitle, +.sidebarblock > .content > .title { + color: rgba(0, 0, 0, 0.8); +} +---- + +Now tell Asciidoctor to use your custom stylesheet instead of the default one: + + $ asciidoctor -a stylesheet=my-asciidoctor.css document.adoc + +Asciidoctor will embed the contents of your custom stylesheet instead of the default one. +However, it will not embed the contents of the default stylesheet, so the browser is still going to go out and fetch it. + +To learn more about how to apply a custom stylesheet, see xref:custom-stylesheet.adoc[]. + +== Are there different themes? + +The default stylesheet does not provide different themes. +However, you can find stylesheets with different themes in the https://github.com/darshandsoni/asciidoctor-skins[Asciidoctor Skins^] project. +These stylesheets take the approach of loading the default stylesheet (from a CDN), then overlaying additional styles to create a variety of themes. + +To learn how to apply a custom stylesheet, see xref:custom-stylesheet.adoc[]. diff --git a/docs/modules/html-backend/pages/favicon.adoc b/docs/modules/html-backend/pages/favicon.adoc new file mode 100644 index 00000000..a6400aff --- /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 `standalone` 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..f3097f83 --- /dev/null +++ b/docs/modules/html-backend/pages/index.adoc @@ -0,0 +1,84 @@ += Generate HTML from AsciiDoc +:navtitle: Generate HTML + +== HTML 5 converter + +Asciidoctor's default output format is HTML. + +`html`:: The HTML 5 converter (`html` or `html5`) generates HTML 5 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 built-in HTML converter. + +=== Create and save an AsciiDoc document + +. To follow along with the steps below, use your own AsciiDoc file or copy the contents of <<ex-my-doc>> into a new plaintext file. ++ +.my-document.adoc +[source#ex-my-doc,asciidoc] +---- +include::example$my-document.adoc[tags=title;body] +---- + +. Make sure to save the file with the _.adoc_ file extension. + +=== Convert an AsciiDoc document to HTML + +To convert [.path]_my-document.adoc_ to HTML from the command line: + +. Open a terminal. +. Switch to the directory that contains the [.path]_my-document.adoc_ document +. Call the Asciidoctor processor with the `asciidoctor` command, followed by the name of the document. ++ +-- + $ asciidoctor my-document.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. +Type `ls` to view the files in the directory or navigate to the directory in a file manager. +You should see a new file named [.path]_my-document.html_. ++ +-- + $ ls + my-document.adoc my-document.html + +Asciidoctor derives the name of the output document from the name of the input document. +-- + +. Open [.path]_my-document.html_ in your web browser. +Your document should look like the image below. ++ +-- +image::my-document.png[] + +The document's text, titles, and link are styled by the default Asciidoctor stylesheet, which is embedded in the HTML output. +As a result, you could save [.path]_my-document.html_ to any computer and it will look the same. +-- + +[#xhtml] +== Generate XHTML + +`xhtml`:: The XHTML variant of the HTML 5 converter. +To use the XHTML converter, assign `xhtml` or `xhtml5` to the `backend` option. + +.Produce XHTML using the xhtml5 backend option + $ asciidoctor -b xhtml5 my-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 + $ asciidoctor -T /path/to/templates -b slides -a htmlsyntax=xml my-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..94323a93 --- /dev/null +++ b/docs/modules/html-backend/pages/manage-images.adoc @@ -0,0 +1,33 @@ += 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. + +== Embed images with the data-uri attribute + +As an alternative, you can embed the images directly into the document by setting the `data-uri` document attribute. + +.data-uri attribute set in document header +[source,asciidoc] +---- +include::example$my-document.adoc[tag=title] +:imagesdir: my-images +:data-uri: +include::example$my-document.adoc[tags=body;image] +---- + +You can also set `data-uri` using the API or CLI (shown here): + + $ asciidoctor -a data-uri my-document.adoc + +When you view the HTML file in your browser, you should see the image displayed in the page. + +image::my-document-with-data-uri.png[] + +== allow-uri-read attribute + +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-document.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/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/source-highlighting-stylesheets.adoc b/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc new file mode 100644 index 00000000..447595ad --- /dev/null +++ b/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc @@ -0,0 +1,27 @@ += Embed a CodeRay or Pygments Stylesheet +// 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:syntax-highlighting:rouge.adoc[], xref:syntax-highlighting:coderay.adoc[], or xref:syntax-highlighting: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/stylesheet-modes.adoc b/docs/modules/html-backend/pages/stylesheet-modes.adoc new file mode 100644 index 00000000..5379ed38 --- /dev/null +++ b/docs/modules/html-backend/pages/stylesheet-modes.adoc @@ -0,0 +1,135 @@ += Stylesheet Modes + +//When applying a stylesheet to the generated HTML, you can configure the HTML converter to either embed the CSS directly into the HTML or link to the stylesheet file. +The HTML converter can be configured to embed the CSS of the stylesheet directly into the HTML, link to the stylesheet file, or disable it entirely. +These modes are available regardless of whether you're using the xref:default-stylesheet.adoc[default stylesheet] or a xref:custom-stylesheet.adoc[custom stylesheet]. +This page covers the document attributes that control how the stylesheet is applied. + +IMPORTANT: The HTML converter will only apply a stylesheet when generating a standalone HTML document. +That's because the stylesheet goes in the HTML `<head>` and the converter only generates this tag for standalone output, not embedded output. + +[#embed] +== Embed the stylesheet + +When the xref:ROOT:safe-modes.adoc[safe mode] is server or lower, the default behavior of the HTML converter is to read the the stylesheet file, enclose its contents in a `<style>` tag, and embed it directly into the `<head>` of the generated HTML. +This default makes the HTML more portable since you don't lose the stylesheet if you move the file. + +However, if the safe mode is secure, the converter will <<link,link to the stylesheet file>> instead. +If you see a link to the stylesheet file in the generated HTML where you expect the stylesheet to be embedded, check your safe mode setting. + +The same two rules apply regardless of whether you're using the default stylesheet or a custom stylesheet. + +[#link] +== Link to the stylesheet + +You already know that the HTML converter will link to the stylesheet when the safe mode is secure. +However, it's possible to enable this behavior independent of the safe mode. +This can be beneficial if you're converting numerous AsciiDoc documents to HTML and want them all to share the same stylesheet. +It can also make inspecting the HTML a little simpler. + +If the `linkcss` document attribute is set, the converter will take this hint to link to the stylesheet using a `<link rel="stylesheet">` tag point to a relative path reference instead of embedding it. + +The `linkcss` document attribute must be set by the end of the header to be effective. +One way to do that is to set the attribute in the document header: + +.linkcss attribute set in document header +[source,asciidoc] +---- +include::example$my-document.adoc[tag=title] +:linkcss: +include::example$my-document.adoc[tag=body] +---- + +You can also set `linkcss` using the API or CLI (shown here): + + $ asciidoctor -a linkcss my-document.adoc + +In either case, if you inspect the `<head>` tag in the output file [.path]_my-document.html_, you'll see that the HTML links to the stylesheet. + +.my-document.html +[source,html] +---- +<link rel="stylesheet" href="./asciidoctor.css"> +---- + +Since we didn't specify a stylesheet, the converter links to the default stylesheet. +But where is this stylesheet located? +Let's find out. + +[#copy] +== Copy the stylesheet to the output directory + +If you're linking to a stylesheet file, the stylesheet file has to be available at the referenced path so the browser can access it. +For simple cases, Asciidoctor takes care of this for you. + +If the safe mode is server or lower, and the `linkcss` document attribute is set, Asciidoctor will copy the stylesheet to the output directory so the HTML can link to it. +When using the default stylesheet, Asciidoctor writes the CSS to the file [.path]_asciidoctor.css_ in the output directory. +If you specify a custom stylesheet, Asciidoctor will copy that file instead, retaining the name of the file. +This utility works even if you specify an xref:cli:output-file.adoc[output file in a different directory] from the source file. + +.A shared responsibility +**** +While the converter handles the task of embedding or linking to the stylesheet file, it's the processor itself (not the converter) that handles copying the stylesheet. +**** + +If the safe mode is secure, Asciidoctor will not copy the stylesheet file and, thus, the link to it will be broken (unless, of course, you copy the file separately). + +Let's revisit the previous example: + + $ asciidoctor -a linkcss my-document.adoc + +After running this command, the stylesheet file [.path]_asciidoctor.css_ is copied to the same directory as the generated HTML file [.path]_my-document.html_. +Type `ls` to view the files in the directory. +You should see a file named [.path]_asciidoctor.css_. + + $ ls + asciidoctor.css my-document.adoc my-document.html + +When you view the HTML file in your browser, you should observe that the default stylesheet is applied. + +=== To copy or not to copy + +Whether Asciidoctor copies the stylesheet to the output directory is controlled by the `copycss` document attribute. +The `copycss` attribute is set by default unless the safe mode is secure. + +To prevent Asciidoctor from copying the stylesheet independent of safe mode, unset the `copycss` document attribute. + +The `copycss` document attribute must be unset by the end of the header to be effective. +One way to do that is to unset the attribute in the document header: + +.copycss attribute unset in document header +[source,asciidoc] +---- +include::example$my-document.adoc[tag=title] +:linkcss: +:!copycss: +include::example$my-document.adoc[tag=body] +---- + +You can also unset `copycss` using the API or CLI (shown here): + + $ asciidoctor -a linkcss -a copycss! my-document.adoc + +In either case, if you inspect the output directory, you will see that the stylesheet file [.path]_asciidoctor.css_ is missing (unless it was already there). + +We'll see the `copycss` attribute come up again on the xref:custom-stylesheet.adoc[custom stylesheet page] as a means of xref:custom-stylesheet.adoc#copy-link-split[overriding the location of the stylesheet to copy]. + +[#disable] +== Disable the stylesheet + +The stylesheet is effectively disabled when generating embedded HTML, since the embedded HTML does not include the `<head>` tag. +If you don't want the converter to include a stylesheet in the standalone HTML, unset the `stylesheet` attribute using the CLI. + + $ asciidoctor -a stylesheet! my-document.adoc + +The reason you have to unset the `stylesheet` attribute is because it is set by default (to an empty value). +When the `stylesheet` attribute is set, but empty, the HTML converter uses the default stylesheet. +By unsetting this attribute, we're telling the converter not to use a stylesheet at all. + +When you view the generated HTML file, [.path]_my-document.html_, you'll see bare HTML without any styles applied, as shown here: + +image::no-stylesheet.png[] + +NOTE: When the `stylesheet` attribute is unset, the `linkcss` and `copycss` attributes are ignored. + +Now that you have a clean slate, let's learn how to apply a custom stylesheet of your very own. 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..a032a193 --- /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,asciidoc] +---- +: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. |
