Commit 60d8205d authored by Sarah White's avatar Sarah White

merge !131

edit docs and remove draft status
parents 917e5de8 47d49f17
Pipeline #17349361 passed with stages
in 3 minutes and 27 seconds
.Basics
* xref:features.adoc[Features]
* xref:pipeline-process.adoc[How Antora Works]
** xref:fetch-content.adoc[Fetch Content]
** xref:load-ui.adoc[Load a UI]
//
* System Requirements
......@@ -26,7 +24,7 @@
.File Organization
* xref:component-structure.adoc[Organize Your Files for Antora]
* xref:modules.adoc[ROOTs & Modules]
* xref:modules.adoc[Modules]
//** Pages & Partials
//** Assets
//** Examples
......
......@@ -5,6 +5,7 @@ endif::[]
// Settings
:idprefix:
:idseparator: -
:underscore: _
A documentation component must contain a component descriptor file named [.path]_antora.yml_.
......@@ -30,13 +31,13 @@ This file provides stable metadata that Antora and other tools can use when they
The component descriptor must:
* be located at the root of the documentation component (adjacent to the [.path]_modules/_ directory for that component)
* be located at the root of the documentation component (adjacent to the [.path]_modules_ directory for that component)
* be named [.path]_antora.yml_
* be written in YAML
* contain the required keys and values
.Component descriptor keys and values
[source,yml]
.Component descriptor structure
[source,yaml]
----
name: component-a # <1>
title: Component A # <2>
......@@ -56,7 +57,7 @@ nav: # <5>
=== name
The value of the name key is the component name that is used when the component is referenced in a xref:asciidoc:page-to-page-xref.adoc#page-id-cname-def[page ID].
The value can contain letter, number, underscore (`_`), hyphen (`-`), and period (`.`) characters.
The value can contain letter, number, underscore (`{underscore}`), hyphen (`-`), and period (`.`) characters.
=== title
......@@ -80,7 +81,7 @@ This includes:
* page version selector
* edit page URI (not visible)
The key's value can contain letter, number, period (`.`), underscore (`_`), and hyphen (`-`) characters.
The key's value can contain letter, number, period (`.`), underscore (`{underscore}`), and hyphen (`-`) characters.
If the value starts with a number, it must be contained within a set of single quote marks (`''`).
.Example version key values
......@@ -107,7 +108,7 @@ start_page: ROOT:overview.adoc
start_page: security:protocols/ssh.adoc
----
IMPORTANT: A component must contain a file named [.path]_index.adoc_ or a start page set in its component descriptor.
IMPORTANT: A component must contain a file named [.path]_index.adoc_ or a start page must be assigned to `start_page` in its component descriptor.
[#nav-key]
=== nav
......
......@@ -26,16 +26,15 @@ All the documentation in a component should follow the same versioning scheme an
Your site can be generated using just one documentation component, or as many as you want.
When Antora receives instructions from your playbook to scan a specific repository, its first objective is to find a component descriptor file in that repository.
The component descriptor file is named [.path]_antora.yml_.
You can learn more about [.path]_antora.yml_ in the xref:antora_yml.adoc[antora.yml reference].
The xref:antora_yml.adoc[component descriptor file] is named [.path]_antora.yml_.
Once Antora finds this file, it assumes that that directory and all its files and subdirectories are a documentation component.
The structure of a documentation component is laid out below.
.Component directory hierarchy
//.Component directory hierarchy
image::component-dir-structure.svg[,240]
The component illustrated in the above figure contains required and reserved directories and files as well as an example of an optional, user created module ([.path]_user-named-module/_).
The component illustrated in the above figure contains required and reserved directories and files as well as an example of an optional, user created module ([.path]_user-named-module_).
When Antora encounters these folders and files in a properly structured component, it automatically assigns preset behavior and metadata to them.
.Component preset legend
......@@ -54,49 +53,49 @@ _Required_; _Reserved_
The component descriptor file tells Antora that the contents of the directory are a documentation component.
This file contains crucial xref:antora_yml.adoc[metadata about the documentation component].
xref:modules.adoc[modules/] ::
xref:modules.adoc[modules] ::
_Required_; _Reserved_
+
Except for [.path]_antora.yml_, all of the files in a component reside in this directory.
xref:modules.adoc#root[modules/ROOT/] ::
xref:modules.adoc#root[modules/ROOT] ::
_Required_; _Reserved_
+
Directory that contains the xref:modules.adoc#root[mandatory ROOT module].
The directory name must be written in all uppercase letters.
xref:modules.adoc#assets-dir[<module>/assets/] ::
xref:modules.adoc#assets-dir[<module>/assets] ::
_Optional_; _Reserved_
+
Directory where multimedia and supplemental files are organized by content type.
xref:modules.adoc#attachments-dir[<module>/assets/attachments/] ::
xref:modules.adoc#attachments-dir[<module>/assets/attachments] ::
_Optional_; _Reserved_
+
Directory that contains supplemental materials, such as PDFs or ZIP files, that readers can download via a link created in a page using the xref:asciidoc:link-attachment.adoc[AsciiDoc link macro].
xref:modules.adoc#images-dir[<module>/assets/images/] ::
xref:modules.adoc#images-dir[<module>/assets/images] ::
_Optional_; _Reserved_
+
Directory that contains pictures, screenshots, diagrams, and other graphics files that are displayed in a page using the xref:asciidoc:insert-image.adoc[AsciiDoc image macro].
<module>/examples/ ::
<module>/examples ::
_Optional_; _Reserved_
+
Directory that contains source, literal, listing, or example block snippets that are inserted into that module's pages.
xref:modules.adoc#pages-dir[<module>/pages/] ::
xref:modules.adoc#pages-dir[<module>/pages] ::
_Required_; _Reserved_
+
Directory that contains all of a module's AsciiDoc files.
These files are automatically enlisted by Antora and converted to standalone HTML pages.
xref:modules.adoc#partials-dir[<module>/pages/_partials/] ::
xref:modules.adoc#partials-dir[<module>/pages/_partials] ::
_Optional_; _Reserved_
+
Directory that contains AsciiDoc files that can be inserted into the files stored directly under [.path]_pages/_.
Directory that contains AsciiDoc files that can be inserted into the files stored directly under [.path]_pages_.
These files are *not* converted to HTML by Antora directly.
Instead, they must be referenced by an xref:asciidoc:include-partial-page.adoc[include directive] in a page in the [.path]_pages/_ directory.
Instead, they must be referenced by an xref:asciidoc:include-partial-page.adoc[include directive] in a page in the [.path]_pages_ directory.
<module>/_attributes.adoc ::
_Required_; _Reserved_
......@@ -110,7 +109,7 @@ A xref:navigation:linked.adoc[linked navigation file] that contains a single, un
Each linked navigation file must be declared in the component descriptor.
The order in which the navigation menus are displayed in the navigation panel is controlled by the order these files are listed in the xref:antora_yml.adoc#nav-key[nav key] of the component descriptor.
modules/user-named-module/ ::
modules/user-named-module ::
_Optional_
+
In addition to the ROOT module, you can create as many additional modules as your documentation component requires.
......
= Antora Pipeline
//= AsciiDoc + Antora = A Web Publishing Pipeline for Docs Teams
= A Source to Web Pipeline for Docs Teams
ifndef::env-site,env-github[]
include::_attributes.adoc[]
endif::[]
// Settings
:idprefix:
:idseparator: -
:tip-caption: RELEASE STATUS
:version: v1.0.0-alpha.6
WARNING: This documentation is ahead of Antora's development.
It will not be accurate until Antora is officially released.
TIP: Antora {version} is now available!
Antora is an end-to-end solution.
It collects source content and outputs a complete site.
......@@ -27,5 +29,7 @@ They can be enlisted, per branch, into the site generation process.
This strategy makes it possible for content branches to be reused, substituted, deactivated, or archived.
This is a sharp contrast to many other site generators, which intermix all these concerns, making the documentation difficult to manage, maintain, and enhance.
////
Let's go over how to xref:component-structure.adoc[organize your documentation] so Antora can use it.
We'll also show you how install Node 8 on xref:install/linux-requirements.adoc[Linux], xref:install/windows-requirements.adoc[Windows], or xref:install/macos-requirements.adoc[macOS] and xref:install/install-antora.adoc[install Antora]. Finally, we'll xref:run-antora-generate-site.adoc[run Antora] and publish a documentation site using a xref:playbook:index.adoc[playbook].
////
......@@ -5,7 +5,7 @@ endif::[]
// Settings
:idprefix:
:idseparator: -
:version: 1.0.0-alpha.5
:version: 1.0.0-alpha.6
On this page, you'll learn:
......
......@@ -5,7 +5,8 @@ endif::[]
// Settings
:idprefix:
:idseparator: -
:version: 1.0.0-alpha.5
:linkattrs:
:version: 1.0.0-alpha.6
On this page, you'll learn:
......@@ -92,5 +93,5 @@ You've now upgraded to the latest version of the Antora CLI and default site gen
== What's next?
* Checkout the https://gitlab.com/antora/antora/blob/master/CHANGELOG.adoc[changelog] to see what's new.
* Checkout the https://gitlab.com/antora/antora/blob/master/CHANGELOG.adoc[changelog^] to see what's new.
* xref:run-antora-generate-site.adoc[Run Antora] and generate a documentation site.
......@@ -28,7 +28,8 @@ Antora requires Node 8, the current long term support (LTS) release of Node.
To check which version of Node you have installed, if any, open PowerShell and type:
$ node --version
[source]
$ node --version
*If the command fails with an error*, you don't have Node installed.
The best way to install Node 8 is via Chocolatey.
......@@ -50,7 +51,8 @@ The best way to install the Node Version Manager (nvm) and Node is with {uri-cho
. Open a PowerShell terminal and run it as an Administrator by right clicking on the PowerShell icon and selecting menu:Run as Administrator[].
. Type the following command in the terminal:
+
[source]
----
$ Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
----
......@@ -65,14 +67,16 @@ TIP: If you just installed Chocolatey using the instructions in the proceeding s
. Open a PowerShell terminal, right click on the PowerShell icon, and select menu:Run as Administrator[].
. To install the {uri-nvm-windows}[Node Version Manager (nvm) for Windows], enter the following command in the terminal:
$ choco install -y nvm
+
[source]
$ choco install -y nvm
. Close the terminal.
. Open an new, regular PowerShell terminal, and install Node with nvm.
$ nvm install {version-node}
+
[source,subs=attributes+]
$ nvm install {version-node}
+
IMPORTANT: When using nvm for Windows, you must enter the full version of Node (i.e., `nvm install {version-node}`) until {uri-nvm-windows}/issues/214[nvm-windows#214] is resolved.
......@@ -82,7 +86,8 @@ Now that Node is installed, you're ready to xref:install/install-antora.adoc[ins
****
You can install the LTS release of Node directly, without installing nvm, by entering the following command in the Administrator PowerShell:
$ choco install -y nodejs-lts
[source]
$ choco install -y nodejs-lts
However, many CI environments use nvm to install the Node version used for the build job.
By using nvm, you closely align your setup with the environment that is used to generate and publish your production site.
......@@ -93,7 +98,8 @@ By using nvm, you closely align your setup with the environment that is used to
If you have nvm installed but your Node version is less than 8.0.0, type the following command in your terminal to install the latest version of Node 8:
$ nvm install {version-node}
[source,subs=attributes+]
$ nvm install {version-node}
IMPORTANT: When using nvm for Windows, you must enter the full version of Node (i.e., `nvm install {version-node}`) until {uri-nvm-windows}/issues/214[nvm-windows#214] is resolved.
......
......@@ -5,6 +5,7 @@ endif::[]
// Settings
:idprefix:
:idseparator: -
:linkattrs:
// URLs
:uri-video-formats: https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#Browser_compatibility
......@@ -18,9 +19,9 @@ A [.term]_module_ is a discrete bundle of content, including text, images, and o
You might be contemplating one or more of the following questions:
[%hardbreaks]
_Why have modules?
Why have modules?
Do we need all this structure?
Isn't a component enough?_
Isn't a component enough?
One thing we've learned about documentation is that it multiplies, often quickly and unpredictably.
As more content is created and your documentation team grows, more often than not, you want to start grouping files into folders to make them easier to find and manage.
......@@ -38,12 +39,12 @@ It's easy to later detach a module from a component and set it up as its own doc
A documentation component must have at least one module, named _ROOT_.
In addition to the ROOT module, you can create as many additional modules in a component as you need.
All of a component's modules must be stored in [.path]_modules/_.
All of a component's modules must be stored in [.path]_modules_.
The following figure illustrates a documentation component with a few example folders and files added for context.
Let's examine the role of each module subdirectory and any associated requirements.
.Module directory hierarchy
//.Module directory hierarchy
image::modules-dir.svg[,260]
We'll start with the ROOT module, since it's required.
......@@ -57,7 +58,7 @@ image::root-dir.svg[,260]
The [.term]_ROOT_ module contains all the content that's directly associated with the documentation component itself.
When the pages in the ROOT module are published, these pages are promoted a level above any other modules' pages in that component's URL.
(You can see an example of a ROOT page's URL in <<pages-dir,Pages>>.)
(You can see an example of a ROOT page's URL in <<pages-dir,pages>>.)
The directory name, ROOT, must be entered in all uppercase letters.
When used in a page reference, it must be entered in all uppercase letters.
......@@ -69,9 +70,9 @@ The ROOT module, as well as any other modules you create, should include the app
For instance:
* AsciiDoc documents go in the [.path]_pages/_ folder.
* Images go in the [.path]_assets/images/_ folder.
* Code snippets go in the [.path]_examples/_ folder.
* AsciiDoc documents go in the [.path]_pages_ folder.
* Images go in the [.path]_assets/images_ folder.
* Code snippets go in the [.path]_examples_ folder.
Each one of these folders can have an arbitrary depth of topic folders that are used to group files to make them easier for you to manage and navigate.
......@@ -84,15 +85,15 @@ Let's look at each of these directories and their content type in more detail.
[#assets-dir]
== Assets
Any attachment, image, and video files associated with a module must be stored in the corresponding content or media type subdirectory under that module's [.path]_assets/_ directory.
Any attachment, image, and video files associated with a module must be stored in the corresponding content or media type subdirectory under that module's [.path]_assets_ directory.
image::assets-dir.svg[,260]
The subdirectory names automatically recognized by Antora and associated to the corresponding AsciiDoc macros are:
* [.path]_assets/attachments/_
* [.path]_assets/images/_
* [.path]_assets/videos/_
* [.path]_assets/attachments_
* [.path]_assets/images_
* [.path]_assets/videos_
You don't need to set the path to these three subdirectories in the header of your AsciiDoc files.
This is managed automatically by Antora.
......@@ -104,14 +105,14 @@ When viewing the file in a preview tool, such as Atom or the Asciidoctor Chrome
=== Attachment files
An attachment is a resource that you want your user to download, such as a PDF or a ZIP archive of a sample project.
Attachment files are saved in [.path]_assets/attachments/_ in the same module where the page that links to that file is located.
Attachment files are saved in [.path]_assets/attachments_ in the same module where the page that links to that file is located.
A link to an attachment is created in a page using the xref:asciidoc:link-attachment.adoc[AsciiDoc link macro].
[#images-dir]
=== Image files
Image files are saved in [.path]_assets/images/_ in the same module where the page that references that image is located.
Image files are saved in [.path]_assets/images_ in the same module where the page that references that image is located.
We also recommend that you mirror the topic hierarchy of the page in which the image is referenced, if the image belongs to a specific page.
Common image file formats include:
......@@ -126,30 +127,30 @@ Images are inserted into a page using the xref:asciidoc:insert-image.adoc[AsciiD
[#videos-dir]
=== Video files
Self-hosted video files are saved in [.path]_assets/videos/_ in the same module where the page that references that video is located.
Self-hosted video files are saved in [.path]_assets/videos_ in the same module where the page that references that video is located.
Video format support is dictated by the user's browser and system.
For a list of the web video formats each browser supports, see the {uri-video-formats}[Mozilla Supported Media Formats documentation].
For a list of the web video formats each browser supports, see the {uri-video-formats}[Mozilla Supported Media Formats documentation^].
Videos are inserted into a page using the xref:asciidoc:embed-video.adoc[AsciiDoc video macro].
=== Large files and GitLab / GitHub
If your documentation component contains large asset files, we do not recommend that you store them in a regular GitLab / GitHub repository.
If your documentation component contains large asset files, we do not recommend that you store them in a regular GitLab or GitHub repository.
Instead, you should either host them in a binary repository such as Bintray or S3, or use git LFS (Large File Storage).
[#examples-dir]
== Examples
The [.path]_examples/_ directory contains source, literal, listing, or example block snippets that are inserted into that module's pages.
The [.path]_examples_ directory contains source, literal, listing, or example block snippets that are inserted into that module's pages.
These files are inserted into a page using the AsciiDoc include directive.
[#pages-dir]
== Pages
AsciiDoc document files go in the [.path]_pages/_ folder of a module.
AsciiDoc document files go in the [.path]_pages_ folder of a module.
image::pages-dir.svg[,260]
......@@ -159,19 +160,19 @@ When the pages in the ROOT module are published, these pages are promoted a leve
Let's say the component illustrated above is the documentation for your newest software product, Hyper Lemur.
What would the URL for [.path]_modules/ROOT/pages/deploy.adoc_ look like?
.URL for deploy.adoc page in ROOT module
//.URL for deploy.adoc page in ROOT module
image::root-page-url.svg[]
The base URL of the site is set in the playbook.
The component name, in this case _hyperlemur_, is set in the [.path]_antora.yml_ file of the documentation component.
The page name segment is the basename of the AsciiDoc file.
Notice that the name of the module, ROOT, isn't in the URL.
Files that are stored directly in the [.path]_ROOT/_ folder are published at the root of the component.
Files that are stored directly in the [.path]_ROOT_ folder are published at the root of the component.
In contrast, pages that are stored in other modules (i.e., not in [.path]_ROOT/_), will be preceded by the name of the module.
In contrast, pages that are stored in other modules (i.e., not in [.path]_ROOT_), will be preceded by the name of the module.
Let's see what the URL for [.path]_modules/a-module/pages/user-management.adoc_ would look like.
.URL for user-management.adoc page in a-module
//.URL for user-management.adoc page in a-module
image::module-page-url.svg[]
The module name is the name of the module directory where that page is stored.
......@@ -183,8 +184,8 @@ Learn more:
[#partials-dir]
=== Partial AsciiDoc files
Partial AsciiDoc files are stored in [.path]_pages/_partials/_ in the same module as the page or pages that embed it.
You don't need to set the path to the [.path]_{blank}_partials/_ directory in the header of the primary AsciiDoc file.
Partial AsciiDoc files are stored in [.path]_pages/_partials_ in the same module as the page or pages that embed it.
You don't need to set the path to the [.path]_{blank}_partials_ directory in the header of the primary AsciiDoc file.
This is managed automatically by Antora.
When viewing the file in a preview tool, the path is managed by the adjacent [.path]_{blank}_attributes.adoc_ file.
......
......@@ -75,8 +75,8 @@ In the terminal, type:
Antora will clone the content repository, convert the AsciiDoc pages to embeddable HTML, wrap the HTML in the page template from the UI, then assemble the pages together with the assets under the destination folder, which defaults to _build/site_.
The repositories are cached under the [.path]_build/site/_ directory.
If you remove the [.path]_build/_ directory, the repositories will have to be downloaded again the next time you run `antora demo-site.yml`.
The repositories are cached under the [.path]_build/site_ directory.
If you remove the [.path]_build_ directory, the repositories will have to be downloaded again the next time you run `antora demo-site.yml`.
[#using-private-repositories]
=== Private GitHub repositories
......
......@@ -23,7 +23,6 @@
* xref:ui-macros.adoc[UI Macros]
* xref:admonitions.adoc[Admonitions]
* xref:examples.adoc[Examples]
* xref:quote-excerpts.adoc[Quote & Prose Excerpts]
* xref:sidebar.adoc[Sidebars]
* xref:include-partial-page.adoc[Insert a Partial Page]
* xref:comments.adoc[Comments]
......@@ -5,6 +5,7 @@ endif::[]
// Settings
:idprefix:
:idseparator: -
:linkattrs:
// External URIs
:uri-adoc-manual: http://asciidoctor.org/docs/user-manual
:uri-admonition: {uri-adoc-manual}/#admonition
......@@ -90,4 +91,4 @@ Use an example block to create an admonition that contains complex content, such
[discrete]
==== Asciidoctor resources
* {uri-admonition}[Admonition paragraphs and blocks]
* {uri-admonition}[Admonition paragraphs and blocks^]
......@@ -6,6 +6,8 @@ endif::[]
:idprefix:
:idseparator: -
:example-caption!:
:linkattrs:
:underscore: _
// External URIs
:uri-adoc-manual: http://asciidoctor.org/docs/user-manual
:uri-bold-italic: {uri-adoc-manual}/#bold-and-italic
......@@ -17,14 +19,14 @@ On this page, you'll learn:
== Bold and italic syntax
To apply bold styling to a word or phrase, place an asterisk (`*`) at the beginning and end of the text you wish to format.
To bold one or a few characters bounded by other characters, place two asterisks (`**`) before and after the characters.
To apply bold styling to a word or phrase, place an asterisk (`{asterisk}`) at the beginning and end of the text you wish to format.
To bold one or more characters bounded by other characters, place two asterisks (`{asterisk}{asterisk}`) before and after the characters.
Words are italicized when they're enclosed in a single set of underscores (`_`).
Bounded characters are italicized by a set of two underscores (`__`).
Words are italicized when they're enclosed in a single set of underscores (`{underscore}`).
Bounded characters are italicized by a set of two underscores (`{underscore}{underscore}`).
.Bold and italic inline formatting
[source,asciidoc]
[source,asciidoc,subs=replacements]
----
*bold phrase* & **char**acter**s**
......@@ -49,4 +51,4 @@ Bold and italicized text can also be xref:monospace.adoc[monospaced].
[discrete]
==== Asciidoctor resources
* {uri-bold-italic}[Bold and italic text formatting]
* {uri-bold-italic}[Bold and italic text formatting^]
......@@ -5,6 +5,7 @@ endif::[]
// Settings
:idprefix:
:idseparator: -
:linkattrs:
// External URIs
:uri-adoc-manual: http://asciidoctor.org/docs/user-manual
:uri-comments: {uri-adoc-manual}/#comments
......@@ -37,6 +38,7 @@ All of the text, including any AsciiDoc syntax, won't be visible when the file i
////
----
Asciidoctor resources:
[discrete]
==== Asciidoctor resources
* {uri-comments}[Comment lines and blocks]
* {uri-comments}[Comment lines and blocks^]
......@@ -6,6 +6,7 @@ endif::[]
:idprefix:
:idseparator: -
:example-caption!:
:linkattrs:
// External URIs
:uri-adoc-manual: http://asciidoctor.org/docs/user-manual
:uri-block: {uri-adoc-manual}/#blocks
......@@ -66,5 +67,5 @@ TIP: xref:admonitions.adoc[Complex admonitions] use the delimited example block
[discrete]
==== Asciidoctor resources
* {uri-block}[Block titles and attributes]
* {uri-block-subs}[Substitutions by block type]
* {uri-block}[Block titles and attributes^]
* {uri-block-subs}[Substitutions by block type^]
......@@ -6,6 +6,8 @@ endif::[]
:idprefix:
:idseparator: -
:example-caption!:
:linkattrs:
:underscore: _
// External URIs
:uri-adoc-manual: http://asciidoctor.org/docs/user-manual
:uri-url: {uri-adoc-manual}/#url
......@@ -15,7 +17,7 @@ endif::[]
On this page, you'll learn:
* [x] When you should use a URL instead of a cross reference.
* [x] When you should use a URL versus a cross reference.
* [x] How to create links with and without link text.
* [x] How to escape a URL.
* [x] How to handle complex URLs.
......@@ -25,7 +27,7 @@ On this page, you'll learn:
Use AsciiDoc's URL syntax when you need to create a link to an external URL.
External URLs are links to webpages that aren't built as part of your documentation site by your Antora pipeline.
When you want to link to a page that is part of your documentation site, use the xref:page-to-page-xref.adoc[cross reference syntax] instead.
When you want to link to a page that is part of your documentation site, use the xref:page-to-page-xref.adoc[page cross reference] instead.
== URL syntax
......@@ -33,11 +35,9 @@ To create a link to an external URL, all you need to do is add the URL prefixed
.Raw URL syntax
[source,asciidoc]
----
Chat with other documentation writers at https://gitter.im/antora/users.
----
Links that begin with official URI schemes, such as `https`, `ftp`, `mailto`, etc., are automatically turned into hyperlinks when they're processed.
Links that begin with official schemes, such as `https`, `ftp`, `mailto`, etc., are automatically turned into hyperlinks when they're processed.
.Result
====
......@@ -62,7 +62,7 @@ Visit the https://gitter.im/antora/users[Antora chat room].
[discrete]
==== Asciidoctor resources
* {uri-url}[URL syntax and attributes]
* {uri-url}[URL syntax and attributes^]
== Escape a URL
......@@ -82,22 +82,22 @@ This URL is displayed, \https://gitlab.com, but isn't clickable.
[discrete]
==== Asciidoctor resources
* {uri-prevent-subs}[Preventing substitutions]
* {uri-prevent-subs}[Preventing substitutions^]
== Troubleshooting URLs
A URL may not display correctly when it contains characters such as underscores (`_`) or carets (`^`) because these characters get interpreted as text formatting markup.
A URL may not display correctly when it contains characters such as underscores (`{underscore}`) or carets (`{caret}`) because these characters get interpreted as text formatting markup.
There are two ways to solve this situation.
. Create a page attribute for the URL.
. Use the inline pass macro with `macros` enabled.
[no-bullet]
* Option 1: Create a page attribute for the URL.
* Option 2: Use the inline pass macro with `macros` enabled.
=== Create a page attribute
Let's make an attribute for a complex URL.
Creating an attribute for a URL is also a good strategy when the URL is long because it keeps the source text clean for writers and editors.
Creating an attribute for a URL is also a good strategy when the URL is long; it keeps the source text clean for writers and editors.
.Page attribute syntax
[source,asciidoc]
......@@ -143,4 +143,4 @@ Anyone want to climb this 13er with me? (pass:macros[https://www.14ers.com/13ers
[discrete]
==== Asciidoctor resources
* {uri-inline-pass}[Inline pass macro and explicit substitutions]
* {uri-inline-pass}[Inline pass macro and explicit substitutions^]
......@@ -6,6 +6,8 @@ endif::[]
:idprefix:
:idseparator: -
:example-caption!:
:linkattrs:
:hash: #
// External URIs
:uri-adoc-manual: http://asciidoctor.org/docs/user-manual
:uri-highlight: {uri-adoc-manual}/#custom-styling-with-attributes
......@@ -16,8 +18,8 @@ On this page, you'll learn:
== Highlight syntax
To apply highlighting to a word or phrase, place a hash (`#`) at the beginning and end of the text you wish to format.
To highlight one or a few characters bounded by other characters, place two hashes (`##`) before and after the characters.
To apply highlighting to a word or phrase, place a hash (`{hash}`) at the beginning and end of the text you wish to format.
To highlight one or more characters bounded by other characters, place two hashes (`{hash}{hash}`) before and after the characters.
.Highlight inline formatting
[source,asciidoc]
......@@ -33,4 +35,4 @@ Let's #highlight this phrase# and the i and the s in th##is##.
[discrete]
==== Asciidoctor resources
* {uri-highlight}[Highlighted text formatting]
* {uri-highlight}[Highlighted text formatting^]
......@@ -5,6 +5,7 @@ endif::[]
// Settings
:idprefix:
:idseparator: -
:linkattrs:
// URLs
:uri-adoc-manual: http://asciidoctor.org/docs/user-manual
:uri-anchor: {uri-adoc-manual}/#anchordef
......@@ -44,7 +45,7 @@ This is an [#name-me] inline ID. //<2>
<1> An ID can be placed on a paragraph (i.e., block).
<2> An ID can be placed inline.
There are some exceptions, see the {uri-anchor}[defining an anchor section in the Asciidoctor manual] for more use cases.
There are some exceptions, see the {uri-anchor}[defining an anchor section in the Asciidoctor manual^] for more use cases.
To link to that ID, use the same in-page xref syntax you use for section headings.
......@@ -57,4 +58,4 @@ We'll walk through a <<playbook,detailed example>> of a playbook in this tutoria
[discrete]
==== Asciidoctor resources
* {uri-anchor}[Define an anchor]
* {uri-anchor}[Define an anchor^]
......@@ -5,6 +5,7 @@ endif::[]
// Settings
:idprefix:
:idseparator: -
:linkattrs:
// URLs
:uri-adoc-manual: http://asciidoctor.org/docs/user-manual
:uri-include: {uri-adoc-manual}/#include-directive
......@@ -12,7 +13,7 @@ endif::[]
[#insert-partial]
== Insert a partial
To insert a partial AsciiDoc file into a standard page, use the include directive (`include::[]`).
To insert a partial AsciiDoc file into a standard page, use the include directive (`+include::[]+`).
.Insert a partial page using an include directive
[source,asciidoc]
......@@ -23,17 +24,17 @@ To insert a partial AsciiDoc file into a standard page, use the include directiv
Let's break this down.
You start with the include directive prefix, `include::`.
Next is the target.
Start the target with the `{partialsdir}/` reference to tell Antora where to look for the file.
Start the target with the `+{partialsdir}+` reference to tell Antora where to look for the file.
Then put the relative path of the partial after that.
Finally, end with a pair of square brackets (`+[]+`).
A module's partial AsciiDoc files should be saved in the xref:ROOT:modules.adoc#partials-dir[+_partials+] catalog.
You don't need to set the path to the [.path]_{blank}_partials/_ directory in the header of your AsciiDoc file.
A xref:ROOT:modules.adoc#partials-dir[module's partial AsciiDoc files] should be saved in the [.path]_{blank}_partials_ directory.
You don't need to set the path to this directory in the header of your AsciiDoc file.
When viewing the file in a preview tool, the path is managed by the adjacent [.path]_{blank}_attributes.adoc_ file.
WARNING: Antora doesn't yet support filtering includes by tag or line number.
NOTE: Antora doesn't yet support filtering includes by tag or line number.
[discrete]
==== Asciidoctor resources
* {uri-include}[Using the AsciiDoc include directive]
* {uri-include}[Using the AsciiDoc include directive^]
......@@ -5,13 +5,14 @@ endif::[]
// Settings
:idprefix:
:idseparator: -
:linkattrs:
// External URIs
:uri-adoc-manual: http://asciidoctor.org/docs/user-manual
:uri-labeled: {uri-adoc-manual}/#labeled-list
On this page, you'll learn:
* [x] How to mark up a labeled or definition list with AsciiDoc.
* [x] How to mark up a labeled list with AsciiDoc.
Labeled lists, also known as definition lists, provide a list of terms or phrases and their descriptions.
......@@ -21,14 +22,13 @@ Each item in a labeled list consists of a term or phrase followed by:
* two consecutive colons, aka a double colon (`::`) separator,
* then at least one space or endline,
* and finally, the description or definition of the item
* and finally, the description or definition of the item.
Here's an example of a labeled list with two terms and their descriptions.
.Labeled list
[source,asciidoc]
----
.Optional title
Keyboard::
Used to enter text or control items on the screen. // <1>
Mouse:: Used to point to and select items on your computer screen. // <2>
......@@ -38,7 +38,6 @@ Mouse:: Used to point to and select items on your computer screen. // <2>
.Result
--
.Optional title
Keyboard::
Used to enter text or control items on the screen.
Mouse:: Used to point to and select items on your computer screen.
......@@ -49,4 +48,4 @@ The description of each item is displayed below the label when rendered.
[discrete]
==== Asciidoctor resources
* {uri-labeled}[Basic and complex labeled lists]
* {uri-labeled}[Basic and complex labeled lists^]