From 450535d3c7661f7d2d6343c3088031996ad24885 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Wed, 22 Dec 2021 20:29:47 -0700 Subject: [PATCH] update What's New for Antora 3.0.0-rc.4 --- .../pages/component-name-and-version.adoc | 2 +- .../ROOT/pages/component-name-key.adoc | 2 +- docs/modules/ROOT/pages/whats-new.adoc | 56 +++++++++++-------- .../optional-component-version-keys.adoc | 4 -- .../required-component-version-keys.adoc | 3 + .../pages/configure-content-sources.adoc | 2 +- .../pages/content-source-version.adoc | 6 +- .../modules/playbook/pages/network-proxy.adoc | 2 +- 8 files changed, 44 insertions(+), 33 deletions(-) diff --git a/docs/modules/ROOT/pages/component-name-and-version.adoc b/docs/modules/ROOT/pages/component-name-and-version.adoc index f124c35a4..c3763f597 100644 --- a/docs/modules/ROOT/pages/component-name-and-version.adoc +++ b/docs/modules/ROOT/pages/component-name-and-version.adoc @@ -32,7 +32,7 @@ Let's create an [.path]_antora.yml_ file that defines the name and version of a In this exercise, we'll create a component version for the project _Silver Leaf_. Its component name will be _silver-leaf_, and its version will be _7.1_. -. Open a new file in the text editor or IDE of your choice. +. Open a new file in your text editor or IDE. . On the first line, type `name`, directly followed by a colon (`:`). . Press the kbd:[Spacebar] to insert a space after the colon, and then type the value you want to assign to `name`. The `name` key doesn't accept certain characters or spaces in its value, see xref:component-name-key.adoc#requirements[name requirements] for details. diff --git a/docs/modules/ROOT/pages/component-name-key.adoc b/docs/modules/ROOT/pages/component-name-key.adoc index e0f0c0bba..b6382abe4 100644 --- a/docs/modules/ROOT/pages/component-name-key.adoc +++ b/docs/modules/ROOT/pages/component-name-key.adoc @@ -48,7 +48,7 @@ The value assigned to the `name` key can contain letters, numbers, underscores ( To ensure portability between host platforms, letters used in the `name` value should be lowercase. IMPORTANT: We *strongly* encouraged you to select a name that only consists of _lowercase_ characters. -Since the component name appears is used in the URL, using consistent casing makes the component name, and thus your site, more portable. +Component names, except for the special _ROOT_ value, are used in your site's URLs, therefore, using consistent casing makes the component name, and thus your site, more portable. That's because some file systems, and thus the web server running on it, can't distinguish between uppercase and lowercase characters. The value *cannot* contain spaces, forward slashes (`/`), or HTML special characters (`&`, `<`, or `>`). diff --git a/docs/modules/ROOT/pages/whats-new.adoc b/docs/modules/ROOT/pages/whats-new.adoc index 1ad68dc79..649af60cf 100644 --- a/docs/modules/ROOT/pages/whats-new.adoc +++ b/docs/modules/ROOT/pages/whats-new.adoc @@ -12,6 +12,16 @@ NOTE: Are you interested in testing the Antora {page-component-display-version} release now? Refer to xref:install:upgrade-antora.adoc[] to find upgrade instructions as well as a checklist to help you prepare. += Antora 3.0.0-rc.4 + +_**Release date:** 2021.12.23 | *Issue label:* {url-milestone-3-0-0}[3.0.0^]_ + +== Resolved issues + +=== Fixed + +Issue {url-issues}/923[#923^]:: Allow extension listeners registered using `once` to accept context variables. + = Antora 3.0.0-rc.3 _**Release date:** 2021.12.22 | *Issue label:* {url-milestone-3-0-0}[3.0.0^]_ @@ -75,8 +85,13 @@ Issue {url-issues}/907[#907^]:: Don't attempt to close logger destination if str == Attachment resource IDs Attachments are now referenced with the AsciiDoc xref macro and their Antora resource IDs. -Make sure to enter the `attachment$` family coordinate in its resource ID when referencing it. -See xref:page:attachments.adoc[] for examples. + +---- +Download the xref:attachment$packet.zip[course materials] before the first class. +---- + +When creating a link to an attachment, make sure to use the `attachment$` family coordinate in its resource ID. +See xref:page:attachments.adoc[] for more examples. == Antora extensions @@ -100,21 +115,6 @@ To learn more, see: * xref:extend:generator-events-reference.adoc[] * xref:extend:generator-context-reference.adoc[] -== Generator in playbook - -As an alternative to the `--generator` CLI option, it's now possible to specify the custom generator in the playbook using the `antora.generator` key. -The key accepts the same value as the CLI option (i.e., a path or require request). - -As part of this change, the meaning of the path prefixes changed to align with other paths defined in the playbook. -If the first path segment is a tilde (`~`), the path is resolved relative to the user's home directory. -If the first path segment is a dot (`.`), the path is resolved relative to the playbook file. -If the first path segment is a tilde plus (`~+`), the path is resolved relative to the current directory. -If the path is a relative path with a file extension and without any of these prefixes, the path is resolved relative to the current directory. -For portability, you're encourage to always use either the `./` or `~+` prefix when specifying a relative path. - -The value also accepts any require request (i.e., module name) supported by Antora's user require helper. -See the https://gitlab.com/antora/user-require-helper/-/blob/main/README.adoc#user-content-usage[@antora/user-require-helper documentation^] details. - == Structured JSON and prettified logging Antora now provides the infrastructure for logging, shaping, and reporting application messages with the introduction of the Antora Logger component. @@ -126,8 +126,8 @@ The logging in Antora 3 can be configured with the following keys: * The xref:playbook:runtime-log-level.adoc[log.level playbook key] specifies a severity threshold, such as `debug` or `error`, that must be met for a message to be logged. * The xref:playbook:runtime-log-failure-level.adoc[log.failure_level playbook key] specifies the severity threshold that, when met or exceeded, causes Antora to fail on exit with a non-zero exit code. * The xref:playbook:runtime-log-format.adoc#level-format-key[log.level_format key] allows the log level format of JSON messages to be configured as numbers of labels. +* The xref:playbook:runtime-log-destination.adoc[log.destination category key] supports writing log messages to a file or standard stream (`file` key) and settings for buffer size (`buffer_size`), `sync`, and `append`. * The xref:playbook:asciidoc-sourcemap.adoc[asciidoc.sourcemap key] provides additional file and line number information about AsciiDoc blocks to Antora's logger and Asciidoctor extensions. -* The xref:playbook:runtime-log-destination.adoc[runtime.log.destination category key] in the playbook supports writing log messages to a file or standard stream, with additional settings for buffer size, sync, and append. == Latest version URL customizations @@ -166,10 +166,7 @@ To do so, set the component name to the special value `ROOT` and the version to == Map version to git refname The version for a component version can be derived from the git refname. -The mapping is defined using patterns and replacements on the `version` key on the content source in the playbook or on the `version` key in the component descriptor. -The replacement that corresponds to first pattern that matches will be used. -If no pattern is matched, or the value of version is `true`, the refname will be used as the version. -(_Documentation pending. See {url-issues}/761[#761^] and {url-issues}/762[#762^]_.) +The mapping is defined using patterns and replacements on xref:playbook:content-source-version.adoc[the version key on a content source] in the playbook or on xref:component-version-key.adoc[the version key in a component version descriptor]. == Symlinks @@ -219,6 +216,21 @@ If you want to avoid modifying your playbook, you can specify this key using a C However, if this is necessary, you may want to understand why the proxy is failing to route the request. See xref:playbook:network-proxy.adoc[] to learn about Antora's automatic support for industry standard proxy environment variables. +== Generator in playbook + +As an alternative to the `--generator` CLI option, it's now possible to specify the custom generator in the playbook using the `antora.generator` key. +The key accepts the same value as the CLI option (i.e., a path or require request). + +As part of this change, the meaning of the path prefixes changed to align with other paths defined in the playbook. +If the first path segment is a tilde (`~`), the path is resolved relative to the user's home directory. +If the first path segment is a dot (`.`), the path is resolved relative to the playbook file. +If the first path segment is a tilde plus (`~+`), the path is resolved relative to the current directory. +If the path is a relative path with a file extension and without any of these prefixes, the path is resolved relative to the current directory. +For portability, you're encourage to always use either the `./` or `~+` prefix when specifying a relative path. + +The value also accepts any require request (i.e., module name) supported by Antora's user require helper. +See the https://gitlab.com/antora/user-require-helper/-/blob/main/README.adoc#user-content-usage[@antora/user-require-helper documentation^] details. + == Asciidoctor 2 Antora 3.0 depends on the latest patch version of Asciidoctor.js 2.2, which provides Asciidoctor 2.0.x. diff --git a/docs/modules/ROOT/partials/optional-component-version-keys.adoc b/docs/modules/ROOT/partials/optional-component-version-keys.adoc index 89f37a504..af9f254db 100644 --- a/docs/modules/ROOT/partials/optional-component-version-keys.adoc +++ b/docs/modules/ROOT/partials/optional-component-version-keys.adoc @@ -2,10 +2,6 @@ |=== |Optional Key |Description -|xref:component-version-key.adoc[version] -|The `version` key is optional if the value is inherited from the content source in the playbook. -You can specify this key on the content source if you want the value to be automatically derived from the refname or based on a refname mapping. - |xref:component-attributes.adoc[asciidoc.attributes] |The `asciidoc` key accepts the `attributes` key and its nested list of key-value pairs. The key-value pairs listed under `attributes` represent built-in and user-defined xref:page:define-and-modify-attributes.adoc[AsciiDoc attributes] (e.g., `idseparator: '-'`) and xref:page:page-attributes.adoc[page attributes]. diff --git a/docs/modules/ROOT/partials/required-component-version-keys.adoc b/docs/modules/ROOT/partials/required-component-version-keys.adoc index 53bef529f..2e0d08b1d 100644 --- a/docs/modules/ROOT/partials/required-component-version-keys.adoc +++ b/docs/modules/ROOT/partials/required-component-version-keys.adoc @@ -9,4 +9,7 @@ Used as the component coordinate in resource IDs and in the component URL segmen |xref:component-version-key.adoc[version] |Version used with `name` to identify a component version. Used as the version coordinate in resource IDs and as the version segment for a component version's published resource URLs, except when a xref:component-with-no-version.adoc[component version is defined as unversioned]. + +Specifying the `version` key in a component version descriptor file is optional if the value of the key is inherited from the xref:playbook:content-source-version.adoc[content source in the playbook]. +You can specify the `version` key on the content source if you want the value to be automatically derived from the refname or based on a refname mapping. |=== diff --git a/docs/modules/playbook/pages/configure-content-sources.adoc b/docs/modules/playbook/pages/configure-content-sources.adoc index faa38e2e8..d408931ee 100644 --- a/docs/modules/playbook/pages/configure-content-sources.adoc +++ b/docs/modules/playbook/pages/configure-content-sources.adoc @@ -78,7 +78,7 @@ The `sources` key must contain at least one entry with the `url` key defined. All other keys are optional. The xref:content-branches.adoc#default[branches] and xref:content-edit-url.adoc#default[edit_url] keys have built-in values Antora automatically applies at runtime if they're not explicitly defined in the playbook. -The `version` key provides a fallback value for the `version` key in the component version descriptor. +The `version` key provides a fallback value for the `version` key in the xref:ROOT:component-version-descriptor.adoc[component version descriptor (_antora.yml_)]. You should only use it if you're matching a single reference or you want the value to be derived from the refname. [#content-reference] diff --git a/docs/modules/playbook/pages/content-source-version.adoc b/docs/modules/playbook/pages/content-source-version.adoc index 88640ee8f..7a59a8bd7 100644 --- a/docs/modules/playbook/pages/content-source-version.adoc +++ b/docs/modules/playbook/pages/content-source-version.adoc @@ -2,7 +2,7 @@ The `version` key provides a way to control the component version that corresponds to a content source directly from the playbook. The `version` key on the content source is a fallback value. -If the component version descriptor defines a `version` key, the value of that key takes precedence. +If a component version descriptor (an [.path]_antora.yml_ file) defines the `version` key for a component version, the value of that key takes precedence. == version key @@ -13,7 +13,7 @@ A content source can match multiple git references. Thus, a fixed value should only be used if the content source is configured to match a single reference, or if all the references it matches contribute files to the same component version. Otherwise, the value of this key should be `true` or a map of refname projections. -If you want the playbook to be able to control the value of the `version` key, don't set the `version` key in the component descriptor. +If you want the playbook to be able to control the value of the `version` key, don't set the `version` key in xref:ROOT:component-version-descriptor.adoc[the component version descriptor (_antora.yml_ file)]. === Fixed value as version @@ -37,7 +37,7 @@ Instead, it will use the fixed value of the `version` key specified on the conte === refname as version -Since content in Antora is retrieved from a git repository, you may want to use the git refname (branch or tag name) for the content source (where the component version descriptor is stored) as the version. +Since content in Antora is retrieved from a git repository, you may want to use the git refname (branch or tag name) for the content source (where the xref:ROOT:component-version-descriptor.adoc[component version descriptor is stored]) as the version. To do so, assign the reserved value `true` to the `version` key. Antora will substitute the value `true` with the refname dynamically. diff --git a/docs/modules/playbook/pages/network-proxy.adoc b/docs/modules/playbook/pages/network-proxy.adoc index 26b8db5d8..2306b21bf 100644 --- a/docs/modules/playbook/pages/network-proxy.adoc +++ b/docs/modules/playbook/pages/network-proxy.adoc @@ -77,7 +77,7 @@ network: no_proxy: '*' ---- -Antora 2 does not honor the `http_proxy` and `https_proxy` environment variables. +Antora 2 didn't honor the `http_proxy` and `https_proxy` environment variables. If you're migrating from Antora 2 to Antora 3, and you encounter a network error (Bad response: 503), the automatic proxy support in Antora 3 may be the culprit. If the proxy is standing in the way of Antora connecting to an endpoint, you may need to bypass the proxy using the `no_proxy` key. If you want to avoid modifying your playbook, you can specify this key using a CLI option: -- GitLab