From e8b59f364c5c96d087628757454e7a35d271d640 Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Thu, 8 Nov 2018 22:35:46 +0100 Subject: [PATCH 1/2] document how to create page redirects I saw this feature hinted at in the documentation, but no clear documentation provided for how to use it. Given that, this commit documents it, so that it's there for all to refer to in the future. --- docs/modules/asciidoc/pages/page-header.adoc | 80 ++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/docs/modules/asciidoc/pages/page-header.adoc b/docs/modules/asciidoc/pages/page-header.adoc index 2176e6c72..6a5b1a651 100644 --- a/docs/modules/asciidoc/pages/page-header.adoc +++ b/docs/modules/asciidoc/pages/page-header.adoc @@ -5,12 +5,16 @@ :url-author: {url-adoc-manual}/#author-and-email :url-attrs: {url-adoc-manual}/#attributes :url-builtin-attrs: {url-adoc-manual}/#builtin-attributes +:url-netlify-redirects: https://www.netlify.com/docs/redirects/ +:url-meta-tag: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta +:url-nginx-rewrite-return-directive: https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#return On this page, you'll learn: * [x] How to structure a valid AsciiDoc page header. * [x] How to set a page title. * [x] How to add metadata to a page. +* [x] How to configure redirects to one or more pages. * [x] How to set AsciiDoc's built-in page attributes. == Header anatomy @@ -129,6 +133,82 @@ The keywords attribute contains a list of comma-separated values that are assign .... +== Configuring page redirects + +To configure page redirects, you use the `page-alias` attribute. +This attribute contains a comma-separated list of pages that redirect to the current page. + +For example, if `upgrade/service/apache.adoc` was renamed to `upgrade/server/apache.adoc`, then at the top of `upgrade/server/apache.adoc`, add a `page-alias` attribute that references the renamed page: + +[source,asciidoc] +.... += Page Title +:page-aliases: upgrade/service/apache.adoc +.... + +NOTE: The redirected pages must follow xref:page:page-id.adoc[Antora’s Page Identifier rules]. + +To allow Antora to follow redirects, you need to generate them. +To do this, assuming one or more page-alias attributes have been added, use Antora's xref:cli:index.adoc#_commands_and_options[`--redirect-facility` option], and specify one of the four redirect types (`disabled`, `netlify`, `nginx`, or `static`). + +For example, to generate a redirect configuration suitable for use with the NGINX webserver, then you would use the, simplified, command: + +[source,console] +.... +antora --redirect-facility nginx playbook.yml +.... + +Redirects work differently, depending on the value provided. +Below are the examples of generated configurations for each of the four parameters: + +=== nginx + +Antora generates an {url-nginx-rewrite-return-directive}[NGINX rewrite configuration] in a file called `rewrite.conf`, in a new directory called `.etc/nginx`, itself created inside the Playbook's output directory. + +.Generated configuration for Nginx +[source,nginx] +.... +location = /upgrade/service/apache.html { + return 301 /upgrade/server/apache.html; +} +.... + +=== netlify + +Antora generates {url-netlify-redirects}[a Netlify _redirects file] (called `_redirects`) in the Playbook's output directory, containing the generated rewrite configuration. + +.Generated configuration for Netlify +[source] +.... +/upgrade/service/apache.html /upgrade/server/apache.html 301 +.... + +=== static + +Antora generates static bounce pages for each page that is to redirected _from_. +These pages contain: + +. A link to the new, canonical reference. +. A {url-meta-tag}[meta refresh tag] to redirect to the new canonical reference +. A notice, letting the reader know that the old page no longer exists along with the location of the new page. + +.Generated static configuration for ./service/apache.html +[source,html] +.... + + + + + + +Redirect Notice +

Redirect Notice

+

+ The page you requested has been relocated to + http://localhost:5000/server/apache.html. +

+.... + [#page-attrs] == Built-in attributes -- GitLab From 7258b79813fa48519bdc1a964caff3b75b84e8d4 Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Fri, 23 Nov 2018 22:43:58 +0100 Subject: [PATCH 2/2] document the --redirect-facility option in CLI ref While documenting how to configure page redirects, @bandantonio noticed that this option wasn't included in the commands and options documentation. Adding it in this PR as it's directly related. --- docs/modules/cli/pages/index.adoc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/modules/cli/pages/index.adoc b/docs/modules/cli/pages/index.adoc index 75cd31624..c91616889 100644 --- a/docs/modules/cli/pages/index.adoc +++ b/docs/modules/cli/pages/index.adoc @@ -107,6 +107,12 @@ Setting this option implicitly enables the Google Analytics / Tag Manager embed |Boolean |false +|--redirect-facility +|The facility for handling page alias and starting page redirections. +The xref:asciidoc:page-header.adoc#_configuring_page_redirects[supported options] are: `disabled`, `netlify`, `nginx`, and `static`. +|String +|static + |-r, --require |Preload the specified library or script. May be specified multiple times. -- GitLab