Skip to content

Commit 8a48674

Browse files
authored
Add documentation about recommended aspect ratios for @PageImage (#1317)
rdar://144094866
1 parent eb5ba13 commit 8a48674

File tree

2 files changed

+47
-7
lines changed

2 files changed

+47
-7
lines changed

Sources/SwiftDocC/Semantics/Metadata/PageImage.swift

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/*
22
This source file is part of the Swift.org open source project
33

4-
Copyright (c) 2022-2024 Apple Inc. and the Swift project authors
4+
Copyright (c) 2022-2025 Apple Inc. and the Swift project authors
55
Licensed under Apache License v2.0 with Runtime Library Exception
66

77
See https://swift.org/LICENSE.txt for license information
@@ -14,9 +14,19 @@ public import Markdown
1414
/// Associates an image with a page.
1515
///
1616
/// You can use this directive to set the image used when rendering a user-interface element representing the page.
17-
/// For example, use the page image directive to customize the icon used to represent this page in the navigation sidebar,
18-
/// or the card image used to represent this page when using the ``Links`` directive and the ``Links/VisualStyle/detailedGrid``
19-
/// visual style.
17+
///
18+
/// Use the "icon" purpose to customize the icon that DocC uses to represent this page in the navigation sidebar.
19+
/// For article pages, DocC also uses this icon to represent the article in topics sections and in ``Links`` directives that use the `list` visual style.
20+
///
21+
/// > Tip: Page images with the "icon" purpose work best when they're square and when they have good visual clarity at small sizes (less than 20×20 points).
22+
///
23+
/// Use the "card" purpose to customize the image that DocC uses to represent this page inside ``Links`` directives that use the either the `detailedGrid` or the `compactGrid` visual style.
24+
/// For article pages, DocC also incorporates a partially faded out version of the card image in the background of the page itself.
25+
///
26+
/// > Tip: Page images with the "card" purpose work best when they have a 16:9 aspect ratio. Currently, the largest size that DocC displays a card image is 640×360 points.
27+
///
28+
/// If you specify an "icon" page image without specifying a "card" page image, DocC will use the icon as a fallback in places where the card image is preferred.
29+
/// To avoid upscaled pixelated icons in these places, either configure a "card" page image as well or use a scalable vector image asset for the "icon" page image.
2030
public final class PageImage: Semantic, AutomaticDirectiveConvertible {
2131
public static let introducedVersion = "5.8"
2232
public let originalMarkup: BlockDirective

Sources/docc/DocCDocumentation.docc/DocC.symbols.json

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4167,13 +4167,43 @@
41674167
"text" : "You can use this directive to set the image used when rendering a user-interface element representing the page."
41684168
},
41694169
{
4170-
"text" : "For example, use the page image directive to customize the icon used to represent this page in the navigation sidebar,"
4170+
"text" : ""
4171+
},
4172+
{
4173+
"text" : "Use the \"icon\" purpose to customize the icon that DocC uses to represent this page in the navigation sidebar."
4174+
},
4175+
{
4176+
"text" : "For article pages, DocC also uses this icon to represent the article in topics sections and in ``Links`` directives that use the `list` visual style."
4177+
},
4178+
{
4179+
"text" : ""
4180+
},
4181+
{
4182+
"text" : "> Tip: Page images with the \"icon\" purpose work best when they're square and when they have good visual clarity at small sizes (less than 20×20 points)."
4183+
},
4184+
{
4185+
"text" : ""
4186+
},
4187+
{
4188+
"text" : "Use the \"card\" purpose to customize the image that DocC uses to represent this page inside ``Links`` directives that use the either the `detailedGrid` or the `compactGrid` visual style."
4189+
},
4190+
{
4191+
"text" : "For article pages, DocC also incorporates a partially faded out version of the card image in the background of the page itself."
4192+
},
4193+
{
4194+
"text" : ""
4195+
},
4196+
{
4197+
"text" : "> Tip: Page images with the \"card\" purpose work best when they have a 16:9 aspect ratio. Currently, the largest size that DocC displays a card image is 640×360 points."
4198+
},
4199+
{
4200+
"text" : ""
41714201
},
41724202
{
4173-
"text" : "or the card image used to represent this page when using the ``Links`` directive and the ``Links\/VisualStyle\/detailedGrid``"
4203+
"text" : "If you specify an \"icon\" page image without specifying a \"card\" page image, DocC will use the icon as a fallback in places where the card image is preferred."
41744204
},
41754205
{
4176-
"text" : "visual style."
4206+
"text" : "To avoid upscaled pixelated icons in these places, either configure a \"card\" page image as well or use a scalable vector image asset for the \"icon\" page image."
41774207
},
41784208
{
41794209
"text" : "- Parameters:"

0 commit comments

Comments
 (0)