From ed06df923d2f4e9c3f4335bd508a1e1673657899 Mon Sep 17 00:00:00 2001 From: Natik Gadzhi Date: Wed, 9 Aug 2023 15:50:38 -0700 Subject: [PATCH 1/2] docs: Add @PageColor to the customization guide --- .../Semantics/Metadata/Metadata.swift | 1 + ...-appearance-of-your-documentation-pages.md | 21 ++++++++++++++++++- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/Sources/SwiftDocC/Semantics/Metadata/Metadata.swift b/Sources/SwiftDocC/Semantics/Metadata/Metadata.swift index 57d7cd3a92..0136bf4d8d 100644 --- a/Sources/SwiftDocC/Semantics/Metadata/Metadata.swift +++ b/Sources/SwiftDocC/Semantics/Metadata/Metadata.swift @@ -23,6 +23,7 @@ import Markdown /// - ``TechnologyRoot`` /// - ``DisplayName`` /// - ``PageImage`` +/// - ``PageColor`` /// - ``CallToAction`` /// - ``Availability`` /// - ``PageKind`` diff --git a/Sources/docc/DocCDocumentation.docc/customizing-the-appearance-of-your-documentation-pages.md b/Sources/docc/DocCDocumentation.docc/customizing-the-appearance-of-your-documentation-pages.md index 6182e81996..fc33807627 100644 --- a/Sources/docc/DocCDocumentation.docc/customizing-the-appearance-of-your-documentation-pages.md +++ b/Sources/docc/DocCDocumentation.docc/customizing-the-appearance-of-your-documentation-pages.md @@ -79,7 +79,26 @@ of a green hue. As a general rule, the default color properties provided by DocC assumes a naming convention where "fill" colors are used for backgrounds and "figure" -colors are used for foreground colors, like text. +colors are used for foreground colors, like text. Note that colors defined in +`theme-settings.json` will be used across all pages of your documentation bundle. + +**Changing a color on for a specific article page** + +You can also use a ``PageColor`` metadata directive to set the fill color for an +intro section of a specific article: + +``` +# What's New in SlothCreator + +@Metadata { + @PageColor(blue) +} + +... +``` + +`@PageColor` only supports a subset of predefined color values: `blue`, +`gray`, `green`, `orange`, `purple`, `red`, `yellow`. > Tip: > For a more complete example of a fully customized documentation website, you From 51c1dd9fdc006718835e204f8e1945ef5616376c Mon Sep 17 00:00:00 2001 From: Natik Gadzhi Date: Mon, 21 Aug 2023 13:50:35 -0700 Subject: [PATCH 2/2] Reworked @pageColor documentation --- ...-appearance-of-your-documentation-pages.md | 28 +++++++------------ 1 file changed, 10 insertions(+), 18 deletions(-) diff --git a/Sources/docc/DocCDocumentation.docc/customizing-the-appearance-of-your-documentation-pages.md b/Sources/docc/DocCDocumentation.docc/customizing-the-appearance-of-your-documentation-pages.md index fc33807627..8e73b037b5 100644 --- a/Sources/docc/DocCDocumentation.docc/customizing-the-appearance-of-your-documentation-pages.md +++ b/Sources/docc/DocCDocumentation.docc/customizing-the-appearance-of-your-documentation-pages.md @@ -82,24 +82,6 @@ naming convention where "fill" colors are used for backgrounds and "figure" colors are used for foreground colors, like text. Note that colors defined in `theme-settings.json` will be used across all pages of your documentation bundle. -**Changing a color on for a specific article page** - -You can also use a ``PageColor`` metadata directive to set the fill color for an -intro section of a specific article: - -``` -# What's New in SlothCreator - -@Metadata { - @PageColor(blue) -} - -... -``` - -`@PageColor` only supports a subset of predefined color values: `blue`, -`gray`, `green`, `orange`, `purple`, `red`, `yellow`. - > Tip: > For a more complete example of a fully customized documentation website, you > can check out [this fork][3] of the DocC documentation that is using this @@ -258,6 +240,16 @@ be added as necessary for other features. } ``` +### Customizing the appearance of specific pages + +Aside from the customizations available via `theme-settings.json`, Swift DocC +provides several directives that allow you to customize just +one specific Article page. + +Most notably: +- ``PageImage`` allows you to set a header image of a page. +- ``PageColor`` allows you to set an accent color of a page. + [1]: https://github.com/apple/swift-docc/blob/main/Sources/SwiftDocC/SwiftDocC.docc/Resources/ThemeSettings.spec.json [2]: https://drafts.csswg.org/css-variables/ [3]: https://mportiz08.github.io/swift-docc/documentation/docc