From 84d34ebf005ac5776f25346b9f52433031510ed7 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Tue, 30 Jan 2018 16:32:11 -0700 Subject: [PATCH 01/14] add page overview docs file --- docs/modules/ROOT/pages/page.adoc | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 docs/modules/ROOT/pages/page.adoc diff --git a/docs/modules/ROOT/pages/page.adoc b/docs/modules/ROOT/pages/page.adoc new file mode 100644 index 000000000..49d5f1457 --- /dev/null +++ b/docs/modules/ROOT/pages/page.adoc @@ -0,0 +1,26 @@ += Page +ifndef::env-site,env-github[] +include::_attributes.adoc[] +endif::[] +// Settings +:idprefix: +:idseparator: - + +On this page, you'll learn: + +* [x] The capabilities of a documentation page written in AsciiDoc. +* [x] How Antora handles pages. +// * [x] Full explanation of a page, including its purpose, types, structure, and behaviors. + +Antora generates site pages from AsciiDoc files. +AsciiDoc files are text files marked up with the AsciiDoc syntax and saved with the file extension `.adoc`. + +How Antora processes an AsciiDoc file depends on where it is stored in a documentation component. +There are three ways to assemble the content of an individual page: standard, quantum, and disco. + +NOTE: Hey, these names are arbitrary, so we decided to have a little fun. + +== Standard page + +Antora generates a site page from an AsciiDoc file. +All of the AsciiDoc files (`.adoc`) located in the [.path]_pages_ directory of a module are converted to individual HTML pages automatically. -- GitLab From eee018632fb4982e4dd48aec42861f0c5c184d3e Mon Sep 17 00:00:00 2001 From: Sarah White Date: Wed, 31 Jan 2018 13:55:59 -0700 Subject: [PATCH 02/14] add standard and partials pages definitions - add component index page definition --- docs/modules/ROOT/pages/modules.adoc | 1 + docs/modules/ROOT/pages/page.adoc | 58 +++++++++++++++++++++++----- 2 files changed, 49 insertions(+), 10 deletions(-) diff --git a/docs/modules/ROOT/pages/modules.adoc b/docs/modules/ROOT/pages/modules.adoc index 6d5bdc1a4..47a4c601a 100644 --- a/docs/modules/ROOT/pages/modules.adoc +++ b/docs/modules/ROOT/pages/modules.adoc @@ -48,6 +48,7 @@ image::modules-dir.svg[,260] We'll start with the ROOT module, since it's required. +[#root-dir] == ROOT module A documentation component must contain a ROOT module directory. diff --git a/docs/modules/ROOT/pages/page.adoc b/docs/modules/ROOT/pages/page.adoc index 49d5f1457..e4ce5f484 100644 --- a/docs/modules/ROOT/pages/page.adoc +++ b/docs/modules/ROOT/pages/page.adoc @@ -1,4 +1,4 @@ -= Page += Pages ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] @@ -8,19 +8,57 @@ endif::[] On this page, you'll learn: -* [x] The capabilities of a documentation page written in AsciiDoc. -* [x] How Antora handles pages. -// * [x] Full explanation of a page, including its purpose, types, structure, and behaviors. +* [x] The difference between a standard and a partial page. +* [x] How Antora handles an [.path]_index.adoc_ file stored in the ROOT module of a component. Antora generates site pages from AsciiDoc files. AsciiDoc files are text files marked up with the AsciiDoc syntax and saved with the file extension `.adoc`. -How Antora processes an AsciiDoc file depends on where it is stored in a documentation component. -There are three ways to assemble the content of an individual page: standard, quantum, and disco. - -NOTE: Hey, these names are arbitrary, so we decided to have a little fun. +Whether Antora automatically processes an AsciiDoc file depends on where it is stored in a documentation component. == Standard page -Antora generates a site page from an AsciiDoc file. -All of the AsciiDoc files (`.adoc`) located in the [.path]_pages_ directory of a module are converted to individual HTML pages automatically. +Antora generates one site page for each AsciiDoc file located in the [.path]_pages_ directory of a module. +These files are converted to individual HTML pages automatically. + +Another way to think about this: one AsciiDoc file in equals one HTML page out. + +my-page.adoc == my-page.html + +Learn more: + +* Create a standard page +* xref:modules.adoc#pages-dir[The _pages_ directory] +* xref:component-structure.adoc[Documentation component overview] + +== Partial page + +Partial pages are AsciiDoc files located in [.path]_pages/_partials_. +These files are *not* converted to HTML by Antora automatically. +Instead, they must be referenced by an xref:page-partials.adoc[include directive] in a standard page. + +Partial pages are good for storing snippets of content, such as concept definitions or project introductions, that you want to reuse in one or more standard pages. +When you change the content in a partial, those changes will be disseminated to all of the standard pages where you embedded that partial with an include directive. + +Learn more: + +* Create a partial page +* xref:modules.adoc#partials-dir[The _{blank}_partials_ directory] +* xref:page-partials.adoc[Include a partial page in a standard page with AsciiDoc] +* xref:component-structure.adoc[Documentation component overview] + +== Component index page + +If a file named [.path]_index.adoc_ exists in the ROOT module of a component, Antora will automatically set this page as the start page of that component. + +component:ROOT:index.adoc == site.com/component/index.html + +Learn more: + +* Create a component index page +//* html extension options +* xref:modules.adoc#root-dir[The ROOT directory] + +// TIP: see the html strategies for dropping the html and index for URLs + +// Site index page -- GitLab From 52d4af8827bd03babcc2489159762dad35724b3a Mon Sep 17 00:00:00 2001 From: Sarah White Date: Wed, 31 Jan 2018 15:02:54 -0700 Subject: [PATCH 03/14] add standard page structure page --- docs/modules/ROOT/pages/page-structure.adoc | 39 +++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/modules/ROOT/pages/page-structure.adoc diff --git a/docs/modules/ROOT/pages/page-structure.adoc b/docs/modules/ROOT/pages/page-structure.adoc new file mode 100644 index 000000000..9905671fd --- /dev/null +++ b/docs/modules/ROOT/pages/page-structure.adoc @@ -0,0 +1,39 @@ += Standard Page Structure +ifndef::env-site,env-github[] +include::_attributes.adoc[] +endif::[] +// Settings +:idprefix: +:idseparator: - + +A standard page is an AsciiDoc file in the [.path]_pages_ directory of a module. +Standard pages have a header, which includes the page title, and a body, which includes the majority of the page's displayed content. + +== Requirements + +* The file must be saved with the extension `.adoc`. +* The file must be marked up with valid AsciiDoc. +* The file must have a page title. + +== Page Header + +The page header is a set of contiguous lines that start on the first line of the file. +The header encapsulates the following elements: + +* page title (required) +* author +* revision information +* environment settings +* built-in document attributes, such as section numbering +* user-defined document attributes, such as keywords and common URLs + +A single blank line signals the end of the page header. +The next line with content is the start of the page body. + +== Page Body + +The page body includes the: + +* preamble +* section headings +* section content such as paragraphs, source code blocks, images, included partials -- GitLab From 772e6b57b54de37a6dd66c48b51335929ada9aea Mon Sep 17 00:00:00 2001 From: Sarah White Date: Wed, 31 Jan 2018 17:58:30 -0700 Subject: [PATCH 04/14] add how to create a new standard page --- docs/modules/ROOT/pages/page-structure.adoc | 54 ++++++++++++++++++--- 1 file changed, 47 insertions(+), 7 deletions(-) diff --git a/docs/modules/ROOT/pages/page-structure.adoc b/docs/modules/ROOT/pages/page-structure.adoc index 9905671fd..845ffeb4b 100644 --- a/docs/modules/ROOT/pages/page-structure.adoc +++ b/docs/modules/ROOT/pages/page-structure.adoc @@ -1,4 +1,4 @@ -= Standard Page Structure += Create a Standard Page ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] @@ -11,29 +11,69 @@ Standard pages have a header, which includes the page title, and a body, which i == Requirements +* The file must be saved in the [.path]_pages_ directory of a module. * The file must be saved with the extension `.adoc`. * The file must be marked up with valid AsciiDoc. * The file must have a page title. -== Page Header +== Page structure + +A standard page has two general parts, a header and a body. The page header is a set of contiguous lines that start on the first line of the file. The header encapsulates the following elements: * page title (required) -* author -* revision information +* author, date, and revision metadata * environment settings * built-in document attributes, such as section numbering * user-defined document attributes, such as keywords and common URLs A single blank line signals the end of the page header. The next line with content is the start of the page body. - -== Page Body - The page body includes the: * preamble * section headings * section content such as paragraphs, source code blocks, images, included partials + +== Create a new standard page + +. Start a new file in a plain text editor such as Atom, Brackets, or gedit. + +. On the first line of file, enter a page title. ++ +A page title is specified by a single equal sign (`=`), followed by one blank space, and then the text of the title. ++ +[source,asciidoc] +---- += The title of my new page +---- + +. On the second line and subsequent contiguous lines, add document metadata and attributes. +*The page title is the only required header element.* + +. Separate the header block from the body block by at least one blank line. + +. Write your content. ++ +[source,asciidoc] +---- += The title of my new page + +Welcome to the preamble of my new page! + +== This is a section title + +This is a paragraph. +---- + +. Save the file. +.. Save the file with the extension `.adoc` in a module's [.path]_pages_ directory. + +.. The name you use when saving the file will be used to compute the page's URL. ++ +my-new-page.adoc -> my-new-page.html + +You've now created a standard page. +When you run Antora, it will be converted to an HTML page and published to your site automatically. -- GitLab From 145fc35764c64b0939be538f7ee79c9985e50847 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Wed, 31 Jan 2018 20:11:44 -0700 Subject: [PATCH 05/14] organize create a standard page sections --- ...ructure.adoc => create-standard-page.adoc} | 70 ++++++++++--------- 1 file changed, 38 insertions(+), 32 deletions(-) rename docs/modules/ROOT/pages/{page-structure.adoc => create-standard-page.adoc} (78%) diff --git a/docs/modules/ROOT/pages/page-structure.adoc b/docs/modules/ROOT/pages/create-standard-page.adoc similarity index 78% rename from docs/modules/ROOT/pages/page-structure.adoc rename to docs/modules/ROOT/pages/create-standard-page.adoc index 845ffeb4b..8b0484777 100644 --- a/docs/modules/ROOT/pages/page-structure.adoc +++ b/docs/modules/ROOT/pages/create-standard-page.adoc @@ -9,41 +9,11 @@ endif::[] A standard page is an AsciiDoc file in the [.path]_pages_ directory of a module. Standard pages have a header, which includes the page title, and a body, which includes the majority of the page's displayed content. -== Requirements - -* The file must be saved in the [.path]_pages_ directory of a module. -* The file must be saved with the extension `.adoc`. -* The file must be marked up with valid AsciiDoc. -* The file must have a page title. - -== Page structure - -A standard page has two general parts, a header and a body. - -The page header is a set of contiguous lines that start on the first line of the file. -The header encapsulates the following elements: - -* page title (required) -* author, date, and revision metadata -* environment settings -* built-in document attributes, such as section numbering -* user-defined document attributes, such as keywords and common URLs - -A single blank line signals the end of the page header. -The next line with content is the start of the page body. -The page body includes the: - -* preamble -* section headings -* section content such as paragraphs, source code blocks, images, included partials - -== Create a new standard page - . Start a new file in a plain text editor such as Atom, Brackets, or gedit. . On the first line of file, enter a page title. + -A page title is specified by a single equal sign (`=`), followed by one blank space, and then the text of the title. +A page title is specified by one equals sign (`=`), followed by one blank space, and then the text of the title. + [source,asciidoc] ---- @@ -60,6 +30,7 @@ A page title is specified by a single equal sign (`=`), followed by one blank sp [source,asciidoc] ---- = The title of my new page +:attribute-a: value-a Welcome to the preamble of my new page! @@ -73,7 +44,42 @@ This is a paragraph. .. The name you use when saving the file will be used to compute the page's URL. + -my-new-page.adoc -> my-new-page.html +my-new-page.adoc => my-new-page.html You've now created a standard page. When you run Antora, it will be converted to an HTML page and published to your site automatically. + +The page created in this example is simple. +Using AsciiDoc, a page's header can encompass a wide range of capabilities and its body can handle complex content. + +== Page header and body structure + +A standard page has two general parts, a header and a body. + +The page header is a set of contiguous lines that start on the first line of the file. +The header encapsulates the following elements: + +* page title (required) +* author, date, and revision metadata +* environment settings +* built-in document attributes, such as section numbering +* user-defined document attributes, such as keywords and common URLs + +A single blank line signals the end of the page header. +The next line with content is the start of the page body. +The page body includes the: + +* preamble +* section headings +* section content such as paragraphs, source code blocks, images, included partials, and much more + +To explore the full capabilities of each AsciiDoc element, check out the documentation under the AsciiDoc collection in the menu on the left. + +[IMPORTANT] +.Key Points to Remember +==== +* The file must be saved in the [.path]_pages_ directory of a module. +* The file must be saved with the extension `.adoc`. +* The file must be marked up with valid AsciiDoc. +* The file must have a page title. +==== -- GitLab From a8de6a2cabfaae8855bca4be1a36086c5fe70684 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Wed, 31 Jan 2018 20:29:04 -0700 Subject: [PATCH 06/14] add pages and standard pages files to nav --- docs/modules/ROOT/nav.adoc | 2 ++ docs/modules/ROOT/pages/modules.adoc | 4 ++++ docs/modules/ROOT/pages/{page.adoc => pages.adoc} | 6 +++--- 3 files changed, 9 insertions(+), 3 deletions(-) rename docs/modules/ROOT/pages/{page.adoc => pages.adoc} (93%) diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index ea13b52fb..8b2fc8e50 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -25,6 +25,8 @@ ** Examples ** xref:antora_yml.adoc[antora.yml] ** Branches & Versions +* xref:pages.adoc[Pages] +** xref:create-standard-page.adoc[Create a Standard Page] * AsciiDoc ** xref:page-assets.adoc[Add Assets to a Page] ** xref:page-partials.adoc[Insert a Partial Page into a Page] diff --git a/docs/modules/ROOT/pages/modules.adoc b/docs/modules/ROOT/pages/modules.adoc index 47a4c601a..b12726561 100644 --- a/docs/modules/ROOT/pages/modules.adoc +++ b/docs/modules/ROOT/pages/modules.adoc @@ -176,6 +176,10 @@ image::module-page-url.svg[] The module name is the name of the module directory where that page is stored. +Learn more: + +* xref:create-standard-page.adoc[Create a standard page] + [#partials-dir] === Partial AsciiDoc files diff --git a/docs/modules/ROOT/pages/page.adoc b/docs/modules/ROOT/pages/pages.adoc similarity index 93% rename from docs/modules/ROOT/pages/page.adoc rename to docs/modules/ROOT/pages/pages.adoc index e4ce5f484..7b65cfe6f 100644 --- a/docs/modules/ROOT/pages/page.adoc +++ b/docs/modules/ROOT/pages/pages.adoc @@ -23,11 +23,11 @@ These files are converted to individual HTML pages automatically. Another way to think about this: one AsciiDoc file in equals one HTML page out. -my-page.adoc == my-page.html +my-page.adoc => my-page.html Learn more: -* Create a standard page +* xref:create-standard-page.adoc[Create a standard page] * xref:modules.adoc#pages-dir[The _pages_ directory] * xref:component-structure.adoc[Documentation component overview] @@ -51,7 +51,7 @@ Learn more: If a file named [.path]_index.adoc_ exists in the ROOT module of a component, Antora will automatically set this page as the start page of that component. -component:ROOT:index.adoc == site.com/component/index.html +component:ROOT:index.adoc => site.com/component/index.html Learn more: -- GitLab From 7a6d0c86232568f3a8bf249abd53fa03d93b1a87 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Wed, 31 Jan 2018 20:38:04 -0700 Subject: [PATCH 07/14] add page header and its sections to nav --- docs/modules/ROOT/nav.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 8b2fc8e50..390ad929b 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -28,6 +28,10 @@ * xref:pages.adoc[Pages] ** xref:create-standard-page.adoc[Create a Standard Page] * AsciiDoc +** xref:page-header.adoc[Header] +*** xref:page-header.adoc#page-title[Page Title] +*** xref:page-header.adoc#page-attrs[Page Attributes] +*** xref:page-header.adoc#page-meta[Page Metadata] ** xref:page-assets.adoc[Add Assets to a Page] ** xref:page-partials.adoc[Insert a Partial Page into a Page] * Cross References -- GitLab From df4f647bb33094f5fbed2960dafac40a45f1f5ef Mon Sep 17 00:00:00 2001 From: Sarah White Date: Wed, 31 Jan 2018 20:54:33 -0700 Subject: [PATCH 08/14] write page header introduction --- docs/modules/ROOT/pages/page-header.adoc | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/modules/ROOT/pages/page-header.adoc diff --git a/docs/modules/ROOT/pages/page-header.adoc b/docs/modules/ROOT/pages/page-header.adoc new file mode 100644 index 000000000..ad48ca3bb --- /dev/null +++ b/docs/modules/ROOT/pages/page-header.adoc @@ -0,0 +1,23 @@ += AsciiDoc Page Header +ifndef::env-site,env-github[] +include::_attributes.adoc[] +endif::[] +// Settings +:idprefix: +:idseparator: - + +On this page, you'll learn: + +* [x] How to structure a valid AsciiDoc page header. +* [x] How to set a page title. +* [x] Where the page title is used in the published site. +* [x] How to set and use AsciiDoc's built-in page attributes. +* [x] How to add page metadata. + +== Page header anatomy + +== Page title + +== Built-in page attributes + +== Page metadata -- GitLab From 994f00b5aa8728c33a54d107715ded17ea46fab9 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Thu, 1 Feb 2018 14:12:23 -0700 Subject: [PATCH 09/14] add page header anatomy section --- docs/modules/ROOT/pages/page-header.adoc | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/modules/ROOT/pages/page-header.adoc b/docs/modules/ROOT/pages/page-header.adoc index ad48ca3bb..091e4bd62 100644 --- a/docs/modules/ROOT/pages/page-header.adoc +++ b/docs/modules/ROOT/pages/page-header.adoc @@ -16,6 +16,27 @@ On this page, you'll learn: == Page header anatomy +.Common elements in a page header +[source,asciidoc] +---- += Page Title // <1> +First Middle Last // <2> +revnumber, revdate: revremark // <3> <4> <5> +:description: A description of the page stored in an HTML meta tag. // <6> +:keywords: comma-separated values, stored, in an HTML, meta, tag // <7> +:sectanchors: // <8> +:url-repo: https://my-git-repo.com // <9> +---- +<1> Title of the page +<2> Author name and email address +<3> Page revision number +<4> Page revision date +<5> Page revision remarks +<6> Page description that is stored in the HTML `meta` tag `description` +<7> Comma-separated list of values that are stored in the HTML `meta` tag `keywords` +<8> Example of a built-in page attribute +<9> Example of a user created and defined page attribute + == Page title == Built-in page attributes -- GitLab From 65e86e36cc80c6e5518381e62e775cf75b38b8a1 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Thu, 1 Feb 2018 14:51:50 -0700 Subject: [PATCH 10/14] add author syntax example and HTML meta output --- docs/modules/ROOT/pages/page-header.adoc | 84 ++++++++++++++++++++---- 1 file changed, 71 insertions(+), 13 deletions(-) diff --git a/docs/modules/ROOT/pages/page-header.adoc b/docs/modules/ROOT/pages/page-header.adoc index 091e4bd62..17aad5579 100644 --- a/docs/modules/ROOT/pages/page-header.adoc +++ b/docs/modules/ROOT/pages/page-header.adoc @@ -21,24 +21,82 @@ On this page, you'll learn: ---- = Page Title // <1> First Middle Last // <2> -revnumber, revdate: revremark // <3> <4> <5> -:description: A description of the page stored in an HTML meta tag. // <6> -:keywords: comma-separated values, stored, in an HTML, meta, tag // <7> -:sectanchors: // <8> -:url-repo: https://my-git-repo.com // <9> +:description: A description of the page stored in an HTML meta tag. // <3> +:keywords: comma-separated values, stored, in an HTML, meta, tag // <4> +:sectanchors: // <5> +:url-repo: https://my-git-repo.com // <6> ---- <1> Title of the page <2> Author name and email address -<3> Page revision number -<4> Page revision date -<5> Page revision remarks -<6> Page description that is stored in the HTML `meta` tag `description` -<7> Comma-separated list of values that are stored in the HTML `meta` tag `keywords` -<8> Example of a built-in page attribute -<9> Example of a user created and defined page attribute +<3> Page description that is stored in the HTML `meta` tag `description` +<4> Comma-separated list of values that are stored in the HTML `meta` tag `keywords` +<5> Example of a built-in page attribute +<6> Example of a user created and defined page attribute == Page title -== Built-in page attributes +A page title is specified by one equals sign (`=`), followed by one blank space, and then the text of the title. ++ +[source,asciidoc] +---- += The title of this page +---- + +The content of a page's title populates the navigation breadcrumb when the site is generated. == Page metadata + +AsciiDoc provides several built-in attributes for defining page metadata. + +=== Author + +Specifying the author of a page is optional. +The author of a page is listed on the line beneath the page’s title. +An optional email address or URL can follow an author’s name inside a set of angle brackets (`< >`). + +.Multiple authors +[source,asciidoc] +---- += Page Title +First Middle Last ; First Middle Last +---- + +When a page has multiple authors, each author is separated by a semicolon (`;`). +The author's name is stored in the HTML `meta` tag `author`. + +.... + + + +... +.... + +Whether the page author information is visible on a generated page depends on the site's UI templates. + +=== Description + +=== Keywords + + + +//// +author:: +The author’s full name, which includes all of the characters or words prior to a semicolon (`;`), angle bracket (`<`) or the end of the line. + +firstname:: +The first word in the author attribute. + +lastname:: +The last word in the author attribute. + +middlename:: +If a firstname and lastname are present, any remaining words or characters found between these attributes are assigned to the middlename attribute. + +authorinitials:: +The first character of the firstname, middlename, and lastname attributes. + +email or contact information:: +An email address or contact information such as a social media account, delimited by angle brackets (`< >`). +//// + +== Built-in page attributes -- GitLab From f7498668177451d2a0ab06cd0f538074ac851ac1 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Thu, 1 Feb 2018 15:09:07 -0700 Subject: [PATCH 11/14] add desc and keywords examples and HTML output --- docs/modules/ROOT/pages/page-header.adoc | 41 +++++++++++++++++++++--- 1 file changed, 37 insertions(+), 4 deletions(-) diff --git a/docs/modules/ROOT/pages/page-header.adoc b/docs/modules/ROOT/pages/page-header.adoc index 17aad5579..e61639777 100644 --- a/docs/modules/ROOT/pages/page-header.adoc +++ b/docs/modules/ROOT/pages/page-header.adoc @@ -36,7 +36,7 @@ First Middle Last // <2> == Page title A page title is specified by one equals sign (`=`), followed by one blank space, and then the text of the title. -+ + [source,asciidoc] ---- = The title of this page @@ -64,20 +64,55 @@ First Middle Last ; First Middle Last When a page has multiple authors, each author is separated by a semicolon (`;`). The author's name is stored in the HTML `meta` tag `author`. +.Author HTML meta tag output +[source,xml] .... -... .... Whether the page author information is visible on a generated page depends on the site's UI templates. === Description +The page attribute `description` is assigned to the HTML `meta` tag with the same name. +If the description is long, you can break value across several lines by ending each line with a backslash `\` that is preceded by a space. + +[source,asciidoc] +---- += Page Title +:description: A description of the page stored in an HTML meta tag. This page is \ +about all kinds of interesting things. +---- + +.Description HTML meta tag output +[source,xml] +.... + + + +.... + === Keywords +The `keywords` attribute contains a list of comma-separated values that are assigned to the HTML `meta` tag with the same name. +[source,asciidoc] +---- += Page Title +:keywords: comma-separated values, stored, in an HTML, meta, tag +---- + +.Keywords HTML meta tag output +[source,xml] +.... + + + +.... + +== Built-in page attributes //// author:: @@ -98,5 +133,3 @@ The first character of the firstname, middlename, and lastname attributes. email or contact information:: An email address or contact information such as a social media account, delimited by angle brackets (`< >`). //// - -== Built-in page attributes -- GitLab From 0ad58509daa529fffbe4f8a6ec2468fd08647608 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Thu, 1 Feb 2018 17:54:03 -0700 Subject: [PATCH 12/14] add built-in page attributes section - add boolean on and off examples - add value override example --- docs/modules/ROOT/pages/page-header.adoc | 109 +++++++++++++++++------ 1 file changed, 80 insertions(+), 29 deletions(-) diff --git a/docs/modules/ROOT/pages/page-header.adoc b/docs/modules/ROOT/pages/page-header.adoc index e61639777..9a84f17cf 100644 --- a/docs/modules/ROOT/pages/page-header.adoc +++ b/docs/modules/ROOT/pages/page-header.adoc @@ -1,20 +1,26 @@ -= AsciiDoc Page Header += Page Header ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] // Settings :idprefix: :idseparator: - +:note-caption: Ops Hint +// URLs +:uri-adoc-manual: http://asciidoctor.org/docs/user-manual On this page, you'll learn: * [x] How to structure a valid AsciiDoc page header. * [x] How to set a page title. * [x] Where the page title is used in the published site. -* [x] How to set and use AsciiDoc's built-in page attributes. -* [x] How to add page metadata. +* [x] How to add metadata to a page. +* [x] How to set AsciiDoc's built-in page attributes. -== Page header anatomy +== Header anatomy + +The page header is a set of contiguous lines that starts on the first line of the file. +The header is separated from the page body by at least one blank line. .Common elements in a page header [source,asciidoc] @@ -28,11 +34,16 @@ First Middle Last // <2> ---- <1> Title of the page <2> Author name and email address -<3> Page description that is stored in the HTML `meta` tag `description` -<4> Comma-separated list of values that are stored in the HTML `meta` tag `keywords` +<3> Description attribute +<4> Keywords attribute <5> Example of a built-in page attribute <6> Example of a user created and defined page attribute +Each attribute entry must be entered on its own line. +Attributes can be placed in any order in the header, including above the page title. +However, the preferred placement is below the title. +The header can also contain line comments. + == Page title A page title is specified by one equals sign (`=`), followed by one blank space, and then the text of the title. @@ -46,38 +57,41 @@ The content of a page's title populates the navigation breadcrumb when the site == Page metadata -AsciiDoc provides several built-in attributes for defining page metadata. +AsciiDoc provides several optional, built-in attributes for defining page metadata. === Author -Specifying the author of a page is optional. -The author of a page is listed on the line beneath the page’s title. -An optional email address or URL can follow an author’s name inside a set of angle brackets (`< >`). +Specifying the author or authors of a page is optional. +The author is listed on the line directly beneath the page’s title. +An optional email address or contact URL can follow an author’s name inside a set of angle brackets (`< >`). .Multiple authors [source,asciidoc] ---- = Page Title -First Middle Last ; First Middle Last +First Middle Last ; First Last ---- When a page has multiple authors, each author is separated by a semicolon (`;`). -The author's name is stored in the HTML `meta` tag `author`. +Author names are stored in the HTML `meta` tag `author`. .Author HTML meta tag output [source,xml] .... - + .... Whether the page author information is visible on a generated page depends on the site's UI templates. +There are additional author attributes and methods for specifying author information. +Refer to the {uri-adoc-manual}/#author-and-email[Asciidoctor user manual] for the complete list of author attributes and usage examples. + === Description -The page attribute `description` is assigned to the HTML `meta` tag with the same name. -If the description is long, you can break value across several lines by ending each line with a backslash `\` that is preceded by a space. +If set, the `description` attribute is stored to the HTML `meta` tag with the same name. +You can break long values across several lines by ending each line with a backslash `\` that is preceded by a space. [source,asciidoc] ---- @@ -114,22 +128,59 @@ The `keywords` attribute contains a list of comma-separated values that are assi == Built-in page attributes -//// -author:: -The author’s full name, which includes all of the characters or words prior to a semicolon (`;`), angle bracket (`<`) or the end of the line. +AsciiDoc provides a multitude of built-in attributes that can activate and control syntax output behavior and styles. + +TIP: If you're not familiar with AsciiDoc attribute restrictions or operations precedence, review the attributes section of the {uri-adoc-manual}/#attributes[Asciidoctor user manual]. + +Page attributes are set in the header and are available to the whole page. +Built-in AsciiDoc attributes are reserved attributes that have special, pre-defined behavior. +Many built-in attributes also have a restricted set of accepted values. + +Built-in page attributes usually fall into one of two types; those that toggle a behavior on or off (boolean) and those that change the generated output by accepting an alternate value or replacement content (variable). + +=== Set and unset built-in attributes + +Let's look at an example of a boolean attribute, `sectanchors`. + +.Set a built-in page attribute +[source,asciidoc] +---- += Page Title +:sectanchors: +---- + +When turned "`on`", the `sectanchors` attribute adds an anchor to the left of each section title that is rendered as the symbol `§`. +The attribute is turned "`on`", also known as "`set`", by simply entering it into the header. + +Built-in attributes that are on by default, such as table captions, can be unset (turned "`off`") with a leading or trailing `!` added to the attribute name. + +.Unset a built-in page attribute +[source,asciidoc] +---- += Page Title +:sectanchors: +:table-caption!: +---- -firstname:: -The first word in the author attribute. +=== Change a built-in attribute value -lastname:: -The last word in the author attribute. +Let's look at an example of a built-in attribute that has a default value that we want to replace with our own value. + +The label on a Note admonition block is controlled by the `note-caption` attribute. +This attribute is on by default and has an implicit (default) value of `NOTE`. +Let's change the label to "`OPS HINT`". + +.Change a built-in page attribute value +[source,asciidoc] +---- += Page Title +:sectanchors: +:table-caption!: +:note-caption: OPS HINT +---- -middlename:: -If a firstname and lastname are present, any remaining words or characters found between these attributes are assigned to the middlename attribute. +Now, when we create a Note admonition block, the block's label should be displayed as OPS HINT. -authorinitials:: -The first character of the firstname, middlename, and lastname attributes. +NOTE: This is an Ops Hint. -email or contact information:: -An email address or contact information such as a social media account, delimited by angle brackets (`< >`). -//// +Refer to the Asciidoctor user manual for a list of all available {uri-adoc-manual}l/#builtin-attributes[built-in page attributes]. -- GitLab From 02fd16ed60ceea260e10a29ca151ee672f86c395 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Thu, 1 Feb 2018 18:21:39 -0700 Subject: [PATCH 13/14] add new page header references to documentation --- docs/modules/ROOT/nav.adoc | 4 ++-- docs/modules/ROOT/pages/create-standard-page.adoc | 10 +++++----- docs/modules/ROOT/pages/page-header.adoc | 3 +++ docs/modules/ROOT/pages/page-partials.adoc | 6 +++--- 4 files changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 390ad929b..14e890f41 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -28,10 +28,10 @@ * xref:pages.adoc[Pages] ** xref:create-standard-page.adoc[Create a Standard Page] * AsciiDoc -** xref:page-header.adoc[Header] +** xref:page-header.adoc[Page Header] *** xref:page-header.adoc#page-title[Page Title] -*** xref:page-header.adoc#page-attrs[Page Attributes] *** xref:page-header.adoc#page-meta[Page Metadata] +*** xref:page-header.adoc#page-attrs[Page Attributes] ** xref:page-assets.adoc[Add Assets to a Page] ** xref:page-partials.adoc[Insert a Partial Page into a Page] * Cross References diff --git a/docs/modules/ROOT/pages/create-standard-page.adoc b/docs/modules/ROOT/pages/create-standard-page.adoc index 8b0484777..0628c55f1 100644 --- a/docs/modules/ROOT/pages/create-standard-page.adoc +++ b/docs/modules/ROOT/pages/create-standard-page.adoc @@ -56,14 +56,14 @@ Using AsciiDoc, a page's header can encompass a wide range of capabilities and i A standard page has two general parts, a header and a body. -The page header is a set of contiguous lines that start on the first line of the file. +The xref:page-header.adoc[page header] is a set of contiguous lines that start on the first line of the file. The header encapsulates the following elements: -* page title (required) -* author, date, and revision metadata +* xref:page-header.adoc#page-title[page title] (required) +* xref:page-header.adoc#page-meta[metadata], such as author information, a page description, and keywords * environment settings -* built-in document attributes, such as section numbering -* user-defined document attributes, such as keywords and common URLs +* xref:page-header.adoc#page-attrs[built-in document attributes], such as section numbering +* user-defined page attributes, such as common replacement text and URLs A single blank line signals the end of the page header. The next line with content is the start of the page body. diff --git a/docs/modules/ROOT/pages/page-header.adoc b/docs/modules/ROOT/pages/page-header.adoc index 9a84f17cf..deb9dd380 100644 --- a/docs/modules/ROOT/pages/page-header.adoc +++ b/docs/modules/ROOT/pages/page-header.adoc @@ -44,6 +44,7 @@ Attributes can be placed in any order in the header, including above the page ti However, the preferred placement is below the title. The header can also contain line comments. +[#page-title] == Page title A page title is specified by one equals sign (`=`), followed by one blank space, and then the text of the title. @@ -55,6 +56,7 @@ A page title is specified by one equals sign (`=`), followed by one blank space, The content of a page's title populates the navigation breadcrumb when the site is generated. +[#page-meta] == Page metadata AsciiDoc provides several optional, built-in attributes for defining page metadata. @@ -126,6 +128,7 @@ The `keywords` attribute contains a list of comma-separated values that are assi .... +[#page-attrs] == Built-in page attributes AsciiDoc provides a multitude of built-in attributes that can activate and control syntax output behavior and styles. diff --git a/docs/modules/ROOT/pages/page-partials.adoc b/docs/modules/ROOT/pages/page-partials.adoc index 9b71e8648..03ec094e7 100644 --- a/docs/modules/ROOT/pages/page-partials.adoc +++ b/docs/modules/ROOT/pages/page-partials.adoc @@ -1,4 +1,4 @@ -= Adding a Partial AsciiDoc File to a Page += Insert a Partial Page into a Standard Page ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] @@ -12,9 +12,9 @@ endif::[] [#insert-partial] == Insert a partial -To insert a partial AsciiDoc file into a page, use the include directive (`include::[]`). +To insert a partial AsciiDoc file into a standard page, use the include directive (`include::[]`). -.Insert a partial file using an include directive +.Insert a partial page using an include directive [source,asciidoc] ---- \include::{partialsdir}/log-definition.adoc[] -- GitLab From 9fd4b7a72df62a9014ff76059f8f220e06732931 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Thu, 1 Feb 2018 18:44:11 -0700 Subject: [PATCH 14/14] add page documentation tasks to roadmap - update status of docs tasks --- roadmap.adoc | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/roadmap.adoc b/roadmap.adoc index ef778fca8..9d075bc4c 100644 --- a/roadmap.adoc +++ b/roadmap.adoc @@ -95,13 +95,13 @@ For current docs.antora.org tasks, see the site {uri-docs-site-issues}[issue tra === v1.0.0-alpha.x -==== Scheduled for alpha.5 release +==== Scheduled for alpha.6 release -* [ ] Add AsciiDoc page overview and structure documentation {uri-issues}/131[#131] +* [x] Add AsciiDoc page overview and structure documentation {uri-issues}/131[#131] * [ ] Document Windows installation instructions {uri-issues}/130[#130] -* [ ] Document output provider and path features {uri-issues}/127[#127] +* [x] Document output provider and path features {uri-issues}/127[#127] -==== Scheduled for alpha.6 release +==== Scheduled for alpha.7 release * [ ] _Docs Site_: Set up automatic deployment to GitLab pages for docs.antora.org {uri-docs-site-issues}/2[#2] * [ ] Document sitemap features @@ -112,6 +112,9 @@ For current docs.antora.org tasks, see the site {uri-docs-site-issues}[issue tra * [ ] Add page ID and xref anatomy diagrams {uri-issues}/76[#76] * [ ] Document redirect features +* [ ] Add how to create a partial page +* [ ] Document how to create user-defined page attributes +* [ ] Expand private repository section {uri-issues}/139[#139] * [ ] Provide source URL configuration examples * [ ] Document UI bundle configuration features * [ ] Document site key configuration features -- GitLab