You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Sources/SwiftDocC/Semantics/Metadata/PageImage.swift
+14-4Lines changed: 14 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
/*
2
2
This source file is part of the Swift.org open source project
3
3
4
-
Copyright (c) 2022-2024 Apple Inc. and the Swift project authors
4
+
Copyright (c) 2022-2025 Apple Inc. and the Swift project authors
5
5
Licensed under Apache License v2.0 with Runtime Library Exception
6
6
7
7
See https://swift.org/LICENSE.txt for license information
@@ -14,9 +14,19 @@ public import Markdown
14
14
/// Associates an image with a page.
15
15
///
16
16
/// 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.
Copy file name to clipboardExpand all lines: Sources/docc/DocCDocumentation.docc/DocC.symbols.json
+33-3Lines changed: 33 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -4167,13 +4167,43 @@
4167
4167
"text" : "You can use this directive to set the image used when rendering a user-interface element representing the page."
4168
4168
},
4169
4169
{
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" : ""
4171
4201
},
4172
4202
{
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."
4174
4204
},
4175
4205
{
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."
0 commit comments