RenderBlockContent.Aside Names #1361

patshaughnessy · 2025-11-19T01:53:27Z

rdar://162549413

Summary

Introduce a new stored property on RenderBlockContent.Aside called name to store the name or title of aside blocks. This allows DocC to independently save and control the styling and the name of asides. Previously DocC conflated the style of the aside block (e.g. colors or other styling) with the name of the aside. Although it isn't currently possible to author an aside with a different style and name, this change allows the Aside model itself to support that one day.

Aside now has four available initializers:

init(style: AsideStyle, content: [RenderBlockContent])
init(name: String, content: [RenderBlockContent])
init(style: AsideStyle, name: String, content: [RenderBlockContent])
init(asideKind: Markdown.Aside.Kind, content: [RenderBlockContent])

Most often DocC will use the fourth initializer to create aside blocks from markdown, via RenderContentCompiler. This initializer, creating an aside from a Swift Markdown Aside.Kind, also contains special logic to determine a capitalized name for the aside that was previously implemented in AsideStyle.

Simplify the RenderBlockContent.AsideStyle structure to act as if it were an enum of the known styles supported by DocC Render: note, tip, experiment, important, or warning. (Since this is public API, this change retains AsideStyle as a structure with a string raw value.)

Also simplify the JSON encoding and decoding of the Aside and AsideStyle structures to save and read the style and name in a natural way.

The precise behaviors of each of the four initializers is listed and tested in SemaToRenderNodeTests.swift:

// The 5 standard styles are encoded and decoded. The names are set to the capitalized style name.
func testEncodingAsidesStandardStyles()

// The 5 standard styles can also be specified by name. The capitalization of the name is retained.
// The style is always lowercase.
func testEncodingAsidesStandardNames() 

// Unknown, custom styles are ignored and coerced to style="note" and name="Note"
func testEncodingAsideCustomStyles() 

// Custom names are supported using style="note"
func testEncodingAsideCustomNames()

// Custom names are supported using style="tip", by specifying both the style and name
func testEncodingTipAsideCustomNames() 

// Asides with a style matching a known kind of Swift Markdown aside are rendered using the display name of the
// Swift Markdown aside kind.
func testEncodingAsideKnownMarkdownKind()

// Asides with a custom/unknown Swift Markdown aside kind capitalize the aside kind to determine the name.
func testEncodingAsideUnknownMarkdownKind()

Dependencies

None.

Testing

Compile documentation that contains aside blocks, and ensure that DocC Render displays them properly.
Deserialize existing Render JSON, adjust some aside blocks to have different style and name values, using init(style: AsideStyle, name: String, content: [RenderBlockContent]), serialize the Render JSON and test DocC Render displays the custom aside properly with the specified name and style. (Note this isn't currently possible to write using DocC markdown syntax.)

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

[x ] Added tests
[x ] Ran the ./bin/test script and it succeeded
~~[ ] Updated documentation if necessary~~

`name` to stored the name or title of aside blocks. This allows DocC to independently save and control the styling and the name of asides. Previously DocC conflated the style of the aside block (e.g. colors or other styling) with the name of the aside. Although it isn't currently possible to author an aside with a different style and name, this change allows the `Aside` model itself to support that one day. Aside now has four available initializers: * init(style: AsideStyle, content: [RenderBlockContent]) * init(name: String, content: [RenderBlockContent]) * init(style: AsideStyle, name: String, content: [RenderBlockContent]) * init(asideKind: Markdown.Aside.Kind, content: [RenderBlockContent]) Most often DocC will use the fourth initializer to create aside blocks from markdown, via RenderContentCompiler. This initializer, creating an aside from a Swift Markdown Aside.Kind, also contains special logic to determine a capitalized name for the aside that was previously implemented in AsideStyle. Simplify the `RenderBlockContent.AsideStyle` structure to act as if it were an enum of the known styles supported by DocC Render: note, tip, experiment, important, or warning. (Since this is public API, this change retains AsideStyle as a structure with a string raw value.) Also simplify the JSON encoding and decoding of Aside and AsideStyle structures to save and read the style and name in a natural way.

patshaughnessy · 2025-11-19T02:00:49Z

@swift-ci please test

patshaughnessy · 2025-11-19T16:38:35Z

@swift-ci please test

mayaepps

Looks good to me, I just left a couple comments.

mayaepps · 2025-11-21T04:30:08Z

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

+        ///   - name: The name of the aside.
+        ///   - content: The block content to display in the aside
+        /// > Note:
+        /// > If the name doesn't match a style supported by DocC Render, set the style to "note".


Thanks for adding these comments!

minor: is the phrase "set the style to "note"" meant to be an instruction to the caller or an explanation of what the aside does internally with the parameters that the caller passes? It would be good to clarify that.

mayaepps · 2025-11-21T04:55:06Z

Tests/SwiftDocCTests/Model/SemaToRenderNodeTests.swift

-        let dashReference = ResolvedTopicReference(bundleID: context.inputs.id, path: "/documentation/Asides/dashAsides()", sourceLanguage: .swift)
+
+        // Instead of creating expected aside objects, type out strings here.
+        // This makes assertion failures much easier to read and parse.


I'm not sure I understand why this is - is it because it will be clearer whether the failure came from the aside name vs. style vs. contents? At first glance, it looks like this test is more complicated now to accommodate this.

mayaepps · 2025-11-21T05:11:03Z

Tests/SwiftDocCTests/Model/SemaToRenderNodeTests.swift

+                }
+                return aside
+            }
+            XCTAssertEqual(25, asides.count)


Nit: this check looks redundant considering the two assertions below should catch if there are the wrong number of asides.

d-ronnqvist

There are 3 categories of changes that I'd ask for:

The structure of the test that divide up the information into 3 separate tests is really hard to follow. Please update it to structure its test inputs so that it's easier to reason about, easier to debug, and easier to update in the future.
There's a fair amount of new public initializers and it was hard for me to tell from the diff if they're all tested. Please check that they are and add any tests that missing.
The documentation comments for the new public initializers confuse me. Please go though them to update any sentence that start with verb like "use" or "set" to clarify who the "actor" is for those sentences; if they are a direction to the caller or a description of what the code does internally.

d-ronnqvist · 2025-12-01T09:33:58Z

Tests/SwiftDocCTests/Model/SemaToRenderNodeTests.swift

+        ]
+
+        // The aside contents from Tests/SwiftDocCTests/Test Resources/Asides.symbols.json
+        let expectedAsideContents = [


Please define a private struct or use a tuple for these arrays. It's near impossible to read this ad know which element in the other 2 arrays that for example "This is wrong.", belong to.

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

d-ronnqvist · 2025-12-01T09:42:56Z

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

+        ///   - name: The name of the aside.
+        ///   - content: The block content to display in the aside
+        /// > Note:
+        /// > If the name doesn't match a style supported by DocC Render, set the style to "note".


minor: is the phrase "set the style to "note"" meant to be an instruction to the caller or an explanation of what the aside does internally with the parameters that the caller passes? It would be good to clarify that.

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

d-ronnqvist · 2025-12-01T09:58:16Z

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

-                style = AsideStyle(displayName: displayName)
-            }
-            self = try .aside(.init(style: style, content: container.decode([RenderBlockContent].self, forKey: .content)))
+            self = try .aside(


question: do we have any tests that verify the backward compatibility of these decoding changes? In other words; are there any tests that decode aside render block values from a handful of JSON data that was created before this?

Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift

d-ronnqvist · 2025-12-01T10:08:22Z

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

There are quite a few new initializers. Does the added tests cover all of them or should we add additional tests so that each initializer is covered?

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

d-ronnqvist · 2025-12-01T10:27:58Z

Tests/SwiftDocCTests/Model/SemaToRenderNodeTests.swift

+
        let asidesSGFURL = Bundle.module.url(
            forResource: "Asides.symbols", withExtension: "json", subdirectory: "Test Resources")!
        let (_, _, context) = try await testBundleAndContext(copying: "LegacyBundle_DoNotUseInNewTests", excludingPaths: []) { url in


If you're significantly updating this test, please also stop relying on "LegacyBundle_DoNotUseInNewTests"

AsideStyle initializers.

Co-authored-by: David Rönnqvist <ronnqvist@apple.com>

…wift Co-authored-by: David Rönnqvist <ronnqvist@apple.com>

patshaughnessy requested review from d-ronnqvist and mayaepps November 19, 2025 01:56

Merge branch 'main' into aside-names

df41366

Correct Swift syntax error that cropped up in macOS CI

22907a3

mayaepps approved these changes Nov 21, 2025

View reviewed changes

d-ronnqvist requested changes Dec 1, 2025

View reviewed changes

patshaughnessy and others added 4 commits December 3, 2025 17:25

Merge branch 'main' into aside-names

74ffb29

Improve the documentation comments for the RenderBlockContent.Aside and

eb1faf7

AsideStyle initializers.

Update Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift

bc31a61

Co-authored-by: David Rönnqvist <ronnqvist@apple.com>

Update Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.s…

bc601cf

…wift Co-authored-by: David Rönnqvist <ronnqvist@apple.com>

RenderBlockContent.Aside Names #1361

Are you sure you want to change the base?

RenderBlockContent.Aside Names #1361

Conversation

patshaughnessy commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Dependencies

Testing

Checklist

Uh oh!

patshaughnessy commented Nov 19, 2025

Uh oh!

patshaughnessy commented Nov 19, 2025

Uh oh!

mayaepps left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mayaepps Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

d-ronnqvist left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

patshaughnessy commented Nov 19, 2025 •

edited

Loading

mayaepps Nov 21, 2025 •

edited

Loading