Skip to content

Add documentation about recommended aspect ratios for @PageImage #1317

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 10, 2025
+47 −7
Merged

Add documentation about recommended aspect ratios for @PageImage #1317

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7fb667f
Add documentation about recommended aspect ratios for @PageImage
d-ronnqvist Oct 9, 2025
9258176
Merge branch 'main' into document-page-image-aspect-ratios
d-ronnqvist Oct 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 14 additions & 4 deletions Sources/SwiftDocC/Semantics/Metadata/PageImage.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/*
This source file is part of the Swift.org open source project

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

See https://swift.org/LICENSE.txt for license information
Expand All @@ -14,9 +14,19 @@ public import Markdown
/// Associates an image with a page.
///
/// You can use this directive to set the image used when rendering a user-interface element representing the page.
/// For example, use the page image directive to customize the icon used to represent this page in the navigation sidebar,
/// or the card image used to represent this page when using the ``Links`` directive and the ``Links/VisualStyle/detailedGrid``
/// visual style.
///
/// Use the "icon" purpose to customize the icon that DocC uses to represent this page in the navigation sidebar.
/// 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.
///
/// > 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).
///
/// 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.
/// For article pages, DocC also incorporates a partially faded out version of the card image in the background of the page itself.
///
/// > 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.
///
/// 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.
/// 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.
public final class PageImage: Semantic, AutomaticDirectiveConvertible {
public static let introducedVersion = "5.8"
public let originalMarkup: BlockDirective
Expand Down
36 changes: 33 additions & 3 deletions Sources/docc/DocCDocumentation.docc/DocC.symbols.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4167,13 +4167,43 @@
"text" : "You can use this directive to set the image used when rendering a user-interface element representing the page."
},
{
"text" : "For example, use the page image directive to customize the icon used to represent this page in the navigation sidebar,"
"text" : ""
},
{
"text" : "Use the \"icon\" purpose to customize the icon that DocC uses to represent this page in the navigation sidebar."
},
{
"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."
},
{
"text" : ""
},
{
"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)."
},
{
"text" : ""
},
{
"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."
},
{
"text" : "For article pages, DocC also incorporates a partially faded out version of the card image in the background of the page itself."
},
{
"text" : ""
},
{
"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."
},
{
"text" : ""
},
{
"text" : "or the card image used to represent this page when using the ``Links`` directive and the ``Links\/VisualStyle\/detailedGrid``"
"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."
},
{
"text" : "visual style."
"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."
},
{
"text" : "- Parameters:"
Expand Down