From 3f8c85cf05a49369cadac9ca3d3397e54cb33f94 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Tue, 30 Jan 2024 12:51:08 +0100 Subject: [PATCH 1/2] Add more information about where to find the Redirected values --- Sources/SwiftDocC/Semantics/Redirect.swift | 17 ++++++++------ .../DocCDocumentation.docc/DocC.symbols.json | 23 +++++++++++++------ 2 files changed, 26 insertions(+), 14 deletions(-) diff --git a/Sources/SwiftDocC/Semantics/Redirect.swift b/Sources/SwiftDocC/Semantics/Redirect.swift index 268e6c6358..dccf4943c9 100644 --- a/Sources/SwiftDocC/Semantics/Redirect.swift +++ b/Sources/SwiftDocC/Semantics/Redirect.swift @@ -12,16 +12,19 @@ import Foundation import Markdown -/// A directive that specifies an additional URL for the page where the directive appears. +/// A directive that specifies a previous URL for the page where the directive appears. /// -/// Use this directive to declare a URL where a piece of content was previously located. -/// For example, if you host the compiled documentation on a web server, -/// that server can read this data and set an HTTP "301 Moved Permanently" redirect from -/// the declared URL to the page's current URL and avoid breaking any existing links to the content. +/// If the page has moved more than once you can add multiple `Redirected` directives, each specifying one previous URL. /// -/// > Note: Starting with version 5.11, @Redirected is supported as a child directive of @Metadata. In -/// previous versions, @Redirected must be used as a top level directive. +/// > Note: Starting with version 5.11, the `Redirected` directive is supported both top-level and as a member of a ``Metadata`` directive. In +/// earlier versions, the `Redirected` directive is only supported as a top-level directive. /// +/// ### Setting up Redirects +/// +/// If you host your documentation on a web server, you can set a HTTP "301 Moved Permanently" redirect for each `Redirected` value to avoid breaking existing links to your content. +/// +/// To find each page's `Redirected` values, pass the `--emit-digest` flag to DocC and read the "linkable-entities.json" file that this makes DocC write to the output directory. +/// Each "entity" in that file has a "path"---which represents the current relative path of that page---and an optional list of "redirects"---which represent all the `Redirected` values for page as they were authored in the markup. You can write either relative redirect values or absolute redirect values depending on what information you need to set HTTP "301 Moved Permanently" redirects on your web server. public final class Redirect: Semantic, AutomaticDirectiveConvertible { public static let introducedVersion = "5.5" public static let directiveName = "Redirected" diff --git a/Sources/docc/DocCDocumentation.docc/DocC.symbols.json b/Sources/docc/DocCDocumentation.docc/DocC.symbols.json index f0c7488256..64eefd8332 100644 --- a/Sources/docc/DocCDocumentation.docc/DocC.symbols.json +++ b/Sources/docc/DocCDocumentation.docc/DocC.symbols.json @@ -4088,35 +4088,44 @@ "docComment" : { "lines" : [ { - "text" : "A directive that specifies an additional URL for the page where the directive appears." + "text" : "A directive that specifies a previous URL for the page where the directive appears." }, { "text" : "" }, { - "text" : "Use this directive to declare a URL where a piece of content was previously located." + "text" : "If the page has moved more than once you can add multiple `Redirected` directives, each specifying one previous URL." }, { - "text" : "For example, if you host the compiled documentation on a web server," + "text" : "" }, { - "text" : "that server can read this data and set an HTTP \"301 Moved Permanently\" redirect from" + "text" : "> Note: Starting with version 5.11, the `Redirected` directive is supported both top-level and as a member of a ``Metadata`` directive. In" }, { - "text" : "the declared URL to the page's current URL and avoid breaking any existing links to the content." + "text" : "earlier versions, the `Redirected` directive is only supported as a top-level directive." }, { "text" : "" }, { - "text" : "> Note: Starting with version 5.11, @Redirected is supported as a child directive of @Metadata. In" + "text" : "### Setting up Redirects" + }, + { + "text" : "" }, { - "text" : "previous versions, @Redirected must be used as a top level directive." + "text" : "If you host your documentation on a web server, you can set a HTTP \"301 Moved Permanently\" redirect for each `Redirected` value to avoid breaking existing links to your content." }, { "text" : "" }, + { + "text" : "To find each page's `Redirected` values, pass the `--emit-digest` flag to DocC and read the \"linkable-entities.json\" file that this makes DocC write to the output directory. " + }, + { + "text" : "Each \"entity\" in that file has a \"path\"---which represents the current relative path of that page---and an optional list of \"redirects\"---which represent all the `Redirected` values for page as they were authored in the markup. You can write either relative redirect values or absolute redirect values depending on what information you need to set HTTP \"301 Moved Permanently\" redirects on your web server." + }, { "text" : "- Parameters:" }, From a87ad1dd3379179c437b7be1a048f39c5259e6ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Fri, 2 Feb 2024 15:08:13 +0100 Subject: [PATCH 2/2] Incorporate feedback from code review --- Sources/SwiftDocC/Semantics/Redirect.swift | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/Sources/SwiftDocC/Semantics/Redirect.swift b/Sources/SwiftDocC/Semantics/Redirect.swift index 8c795b1cbd..c0b5a17d08 100644 --- a/Sources/SwiftDocC/Semantics/Redirect.swift +++ b/Sources/SwiftDocC/Semantics/Redirect.swift @@ -14,7 +14,12 @@ import Markdown /// A directive that specifies a previous URL for the page where the directive appears. /// -/// If the page has moved more than once you can add multiple `Redirected` directives, each specifying one previous URL. +/// If the page has moved more than once you can add multiple `Redirected` directives, each specifying one previous URL. For example: +/// +/// ```md +/// @Redirected(from: "old/path/to/this/page") +/// @Redirected(from: "another/old/path/to/this/page") +/// ``` /// /// > Note: Starting with version 5.11, the `Redirected` directive is supported both top-level and as a member of a ``Metadata`` directive. In /// earlier versions, the `Redirected` directive is only supported as a top-level directive. @@ -23,8 +28,11 @@ import Markdown /// /// If you host your documentation on a web server, you can set a HTTP "301 Moved Permanently" redirect for each `Redirected` value to avoid breaking existing links to your content. /// -/// To find each page's `Redirected` values, pass the `--emit-digest` flag to DocC and read the "linkable-entities.json" file that this makes DocC write to the output directory. -/// Each "entity" in that file has a "path"---which represents the current relative path of that page---and an optional list of "redirects"---which represent all the `Redirected` values for page as they were authored in the markup. You can write either relative redirect values or absolute redirect values depending on what information you need to set HTTP "301 Moved Permanently" redirects on your web server. +/// To find each page’s Redirected values, pass the `--emit-digest` flag to DocC. +/// This flag configures DocC to write additional metadata files to the output directory. +/// One of these files, `linkable-entities.json`, contains summarized information about all pages and on-page landmarks that you can link to from outside the DocC documentation. +/// Each of these "entities" has a `"path"`---which represents the current relative path of that page---and an optional list of `"redirects"`---which represent all the `Redirected` values for page as they were authored in the markup. +/// You can write either relative redirect values or absolute redirect values in the markup depending on what information you need when setting up HTTP "301 Moved Permanently" redirects on your web server. public final class Redirect: Semantic, AutomaticDirectiveConvertible { public static let introducedVersion = "5.5" public static let directiveName = "Redirected"