diff --git a/Sources/SwiftDocC/Semantics/Redirect.swift b/Sources/SwiftDocC/Semantics/Redirect.swift index c0b5a17d08..ac841ca288 100644 --- a/Sources/SwiftDocC/Semantics/Redirect.swift +++ b/Sources/SwiftDocC/Semantics/Redirect.swift @@ -21,7 +21,7 @@ import Markdown /// @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 +/// > Note: Starting with version 6.0, 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 diff --git a/Sources/docc/DocCDocumentation.docc/DocC.symbols.json b/Sources/docc/DocCDocumentation.docc/DocC.symbols.json index 64eefd8332..1c22888139 100644 --- a/Sources/docc/DocCDocumentation.docc/DocC.symbols.json +++ b/Sources/docc/DocCDocumentation.docc/DocC.symbols.json @@ -2001,13 +2001,13 @@ "text" : "" }, { - "text" : "When the ``style`` property is ``Style\/conceptual``, the symbol's name is rendered as \"conceptual\"—same as article names or tutorial names —where applicable. The default style is ``Style\/conceptual``." + "text" : "When the ``style`` property is ``Style\/conceptual``, the symbol's name is rendered as \"conceptual\"---same as article names or tutorial names---where applicable. The default style is ``Style\/conceptual``." }, { "text" : "" }, { - "text" : "When the ``style`` property is ``Style\/symbol``, the symbol's name is rendered as \"symbol\"—same as article names or tutorial names —where applicable. The default style is ``Style\/conceptual``." + "text" : "When the ``style`` property is ``Style\/symbol``, the symbol's name is rendered as \"symbol\"---same as article names or tutorial names---where applicable. The default style is ``Style\/conceptual``." }, { "text" : "" @@ -2247,34 +2247,34 @@ "docComment" : { "lines" : [ { - "text" : "A directive that controls how the documentation-extension file merges with or overrides the in-source documentation." + "text" : "Defines whether the content in a documentation extension file amends or replaces in-source documentation." }, { "text" : "" }, { - "text" : "When the ``behavior`` property is ``Behavior\/append``, the content from the documentation-extension file is added after the content from" + "text" : "By default, content from the documentation-extension file is added after the content from the in-source documentation for that symbol." }, { - "text" : "the in-source documentation for that symbol." + "text" : "" }, { - "text" : "If a documentation-extension file doesn't have a `DocumentationExtension` directive, then it has the ``Behavior\/append`` behavior." + "text" : "You get this default behavior in two cases:" }, { - "text" : "" + "text" : "- when the documentation-extension file doesn't have a `DocumentationExtension` directive" }, { - "text" : "When the ``behavior`` property is ``Behavior\/override``, the content from the documentation-extension file completely replaces the content" + "text" : "- when the `DocumentationExtension` directive explicitly specifies the ``Behavior\/append`` behavior" }, { - "text" : "from the in-source documentation for that symbol" + "text" : "" }, { - "text" : "" + "text" : "The other merge behavior completely replaces the content from the in-source documentation for that symbol with the content from the documentation-extension file. To get this behavior, specify ``Behavior\/override`` as the merge behavior." }, { - "text" : "This directive is only valid within a ``Metadata`` directive:" + "text" : "" }, { "text" : "```" @@ -2291,11 +2291,17 @@ { "text" : "```" }, + { + "text" : "" + }, + { + "text" : "The `DocumentationExtension` is only valid within a ``Metadata`` directive." + }, { "text" : "- Parameters:" }, { - "text" : " - mergeBehavior: The merge behavior for this documentation extension." + "text" : " - mergeBehavior: A value of `append` or `override`, denoting whether an extension file's content amends or replaces the in-source documentation." }, { "text" : " **(required)**" @@ -4094,13 +4100,28 @@ "text" : "" }, { - "text" : "If the page has moved more than once you can add multiple `Redirected` directives, each specifying one previous URL." + "text" : "If the page has moved more than once you can add multiple `Redirected` directives, each specifying one previous URL. For example:" + }, + { + "text" : "" + }, + { + "text" : "```md" + }, + { + "text" : "@Redirected(from: \"old\/path\/to\/this\/page\")" + }, + { + "text" : "@Redirected(from: \"another\/old\/path\/to\/this\/page\")" + }, + { + "text" : "```" }, { "text" : "" }, { - "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" : "> Note: Starting with version 6.0, the `Redirected` directive is supported both top-level and as a member of a ``Metadata`` directive. In" }, { "text" : "earlier versions, the `Redirected` directive is only supported as a top-level directive." @@ -4121,10 +4142,19 @@ "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" : "To find each page’s Redirected values, pass the `--emit-digest` flag to DocC." + }, + { + "text" : "This flag configures DocC to write additional metadata files to the output directory." + }, + { + "text" : "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." + }, + { + "text" : "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." }, { - "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" : "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." }, { "text" : "- Parameters:" @@ -5553,16 +5583,34 @@ "docComment" : { "lines" : [ { - "text" : "A directive to set this page as a documentation root-level node." + "text" : "Configures an article to become a top-level page." }, { "text" : "" }, { - "text" : "This directive is only valid within a top-level ``Metadata`` directive:" + "text" : "If your documentation only consists of articles, without any framework documentation or other top-level pages, DocC will use the only article or the article with the same base name as the documentation catalog ('.docc' directory) as the top-level page." }, { - "text" : "```" + "text" : "If the documentation doesn't contain an article with the same base name as the documentation catalog, DocC will synthesize a minimal top-level page." + }, + { + "text" : "" + }, + { + "text" : "To customize which article is the top-level page of your documentation, add a `TechnologyRoot` directive within a `Metadata` directive in that article:" + }, + { + "text" : "" + }, + { + "text" : "```md" + }, + { + "text" : "# Page Title" + }, + { + "text" : "" }, { "text" : "@Metadata {" @@ -5575,6 +5623,45 @@ }, { "text" : "```" + }, + { + "text" : "" + }, + { + "text" : "> Earlier Versions:" + }, + { + "text" : "> Before Swift-DocC 6.0, article-only documentation catalogs require one of the articles to be marked as a `TechnologyRoot`." + }, + { + "text" : "" + }, + { + "text" : "### Containing Elements" + }, + { + "text" : "" + }, + { + "text" : "The following items can include a technology root element:" + }, + { + "text" : "" + }, + { + "text" : "- ``Metadata``" + }, + { + "text" : "" + }, + { + "text" : "## See Also" + }, + { + "text" : "" + }, + { + "text" : "- " } ] }, diff --git a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md index 78502034ca..ae87602200 100644 --- a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md +++ b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md @@ -42,7 +42,7 @@ Use the `Metadata` directive with the ``TitleHeading`` directive to configure th } ``` -Starting with version 5.11, use the `Metadata` directive with one or more ``Redirected`` directives +Starting with version 6.0, use the `Metadata` directive with one or more ``Redirected`` directives to add additional URLs for a page. ``` # ``SlothCreator`` @@ -53,7 +53,7 @@ to add additional URLs for a page. } ``` -> Note: Starting with version 5.11, @Redirected is supported as a child directive of @Metadata. In +> Note: Starting with version 6.0, @Redirected is supported as a child directive of @Metadata. In previous versions, @Redirected must be used as a top level directive. ## Topics @@ -87,7 +87,7 @@ previous versions, @Redirected must be used as a top level directive. - ``Redirected`` -> Note: Starting with version 5.11, @Redirected is supported as a child directive of @Metadata. In +> Note: Starting with version 6.0, @Redirected is supported as a child directive of @Metadata. In previous versions, @Redirected must be used as a top level directive.