Improve handling of lists when exporting markdown by jrturton · Pull Request #1543 · swiftlang/swift-docc

jrturton · 2026-06-11T13:48:58Z

Bug/issue #, if applicable:

179135030

Summary

Links in list items should get resolved to title + link (179135030)

Ordered and unordered lists were getting directly output using format() unless we were processing a linked list (like a topics section). This bypassed the link resolution / formatting steps that happen when visiting a link.

Changed the processing of lists to find and convert any links or symbol links found in the list item.

Dependencies

N/A

Testing

Create source documentation with article and symbol links inside ordered or unordered lists, and within standard paragraphs of prose. Run convert on the documentation with the --enable-experimental-markdown-output flag enabled. Examine the markdown produced in the docc archive. The links should be formatted the same in the list output as they are in the normal paragraph output.

Checklist

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

Added tests
Ran the ./bin/test script and it succeeded
Updated documentation if necessary (N/A)

- Links in list items should get resolved to title + link (179135030) - Term lists shouldn't render with the word "term" in them (166128254)

d-ronnqvist

Hi, it appears that this is addressing two issues that aren't related to each other (and that seemingly doesn't modify the same lines of code). Can you please open one PR per issue so that it' easier to review the changes?

d-ronnqvist · 2026-06-11T14:07:04Z

Regarding the "Testing" section of the PR description;
This section is meant to contain instructions describing how a reviewer can manually try out and verify the changes. It is expected that all PRs add automated tests to cover their changes. Please fill out the PR template (testing excerpt below) in both PRs.

Describe how a reviewer can test the functionality of your PR. Provide test content to test with if applicable.

Steps:

Provide setup instructions.

Explain in detail how the functionality can be tested.

d-ronnqvist · 2026-06-11T14:10:13Z

Please use Swift Testing for all new tests. See the "Adding new tests" section of the contributing document for more details.

I was planning to migrate all the tests to swift testing as a subsequent PR to this (now these?), to reduce noise - is that OK or would you prefer me to add another file with just the new tests in it?

The contributing document offers some guidance on this; specifically that you can create a new test suite in (even in the same file) that contains only the Swift Testing test(s):

Updating existing tests

If you're updating an existing test case with additional logic, we appreciate if you also modernize that test while updating it, but we don't expect it. If the test case is part of a large file, you can create new test suite which contains just the test case that you're modernizing.

If you modernize an existing test case, consider not only the syntactical differences between Swift Testing and XCTest, but also if there are any Swift Testing features or other changes that would make the test case easier to read, maintain, or debug.

d-ronnqvist · 2026-06-12T12:55:14Z

+                Tests the appearance of nested lists
+
+                ## Overview
+
+                This is a list: 


minor: This markup is never verified in the output and can be removed.

Suggested change

Tests the appearance of nested lists

## Overview

This is a list:

d-ronnqvist · 2026-06-12T12:55:25Z

+
+                ## Topics
+
+                ### No more links
+
+                Empty section


minor: This markup is never verified in the output and can be removed.

Suggested change

## Topics

### No more links

Empty section

d-ronnqvist · 2026-06-12T12:55:37Z

+                This is a list of things that have links:
+
+                - You can use ``MarkdownSymbol`` to do interesting things
+                - You can't use other things


minor: This markup is never verified in the output and can be removed.

Suggested change

- You can't use other things

d-ronnqvist · 2026-06-12T12:56:02Z

+                ## Topics
+
+                ### No more links
+
+                Empty section


minor: This markup is never verified in the output and can be removed.

Suggested change

## Topics

### No more links

Empty section

d-ronnqvist · 2026-06-12T12:56:27Z

+                Tests the appearance of inline and linked lists
+
+                ## Overview
+
+                These are some interesting links that are in list items: 
+


minor: This markup is never verified in the output and can be removed.

Suggested change

Tests the appearance of inline and linked lists

## Overview

These are some interesting links that are in list items:

d-ronnqvist · 2026-06-12T12:56:32Z

+                These are some interesting links that are in ordered list items: 
+


minor: This markup is never verified in the output and can be removed.

Suggested change

These are some interesting links that are in ordered list items:

d-ronnqvist · 2026-06-12T13:01:47Z

    }

-    mutating func visitSymbolLink(_ symbolLink: SymbolLink) {
+    mutating func convertSymbolLink(_ symbolLink: SymbolLink) -> (link: any InlineMarkup, abstract: (any Markup)?)? {


minor: As far as I can tell, this is an implementation details that other types aren't expected to call.

Also, AFAICT this method doesn't mutate the walker.

Suggested change

mutating func convertSymbolLink(_ symbolLink: SymbolLink) -> (link: any InlineMarkup, abstract: (any Markup)?)? {

private func convertSymbolLink(_ symbolLink: SymbolLink) -> (link: any InlineMarkup, abstract: (any Markup)?)? {

d-ronnqvist · 2026-06-12T13:02:15Z


-    mutating func visitLink(_ link: Link) {
-
+    mutating func convertLink(_ link: Link) -> (link: Link, abstract: (any Markup)?) {


minor: As far as I can tell, this is an implementation details that other types aren't expected to call.

Also, AFAICT this method doesn't mutate the walker.

Suggested change

mutating func convertLink(_ link: Link) -> (link: Link, abstract: (any Markup)?) {

private func convertLink(_ link: Link) -> (link: Link, abstract: (any Markup)?) {

d-ronnqvist · 2026-06-12T13:03:17Z

+        return List(newItems)
+    }
+
+    mutating func convertListItem(_ item: ListItem) -> ListItem {


minor: As far as I can tell, this is an implementation details that other types aren't expected to call.

Also, AFAICT this method doesn't mutate the walker.

Suggested change

mutating func convertListItem(_ item: ListItem) -> ListItem {

private func convertListItem(_ item: ListItem) -> ListItem {

This method could also benefit from a brief comment explaining what it does and why. From the signature all I can tell is that it converts a list item to the same type of list item.

d-ronnqvist · 2026-06-12T13:18:04Z

+                var newComponents: [any InlineMarkup] = []
+                for inlineChild in paragraph.inlineChildren {
+                    if let link = inlineChild as? Link {
+                        let (converted, _) = convertLink(link)
+                        newComponents.append(converted)
+                    } else if let symbolLink = inlineChild as? SymbolLink {
+                        if let (converted, _) = convertSymbolLink(symbolLink) {
+                            newComponents.append(converted)
+                        }
+                    } else {
+                        newComponents.append(inlineChild)
+                    }
+                }
+                newChildren.append(Paragraph(newComponents))


minor: It might make this implementation easier to read if this was extracted to a private function (or even an inner function. That would make it clearer at a glance that the outer loop is switching over the element type and calling different convert functions for each type.

d-ronnqvist · 2026-06-12T13:21:34Z

+        var newChildren: [any BlockMarkup] = []
+        for child in item.blockChildren {
+            if let nestedList = child as? any ListItemContainer {
+                let converted = convertList(nestedList)
+                newChildren.append(converted)
+            } else if let paragraph = child as? Paragraph {
+                var newComponents: [any InlineMarkup] = []
+                for inlineChild in paragraph.inlineChildren {
+                    if let link = inlineChild as? Link {
+                        let (converted, _) = convertLink(link)
+                        newComponents.append(converted)
+                    } else if let symbolLink = inlineChild as? SymbolLink {
+                        if let (converted, _) = convertSymbolLink(symbolLink) {
+                            newComponents.append(converted)
+                        }
+                    } else {
+                        newComponents.append(inlineChild)
+                    }
+                }
+                newChildren.append(Paragraph(newComponents))
+            } else {
+                newChildren.append(child)
+            }
+        }


There are a couple patterns hiding in this implementation that I feel make it harder to read than necessary.

Both loops behave like map (but is slower because it doesn't preemptively reserve capacity for the known number of elements) and both if-else expressions behave like a switch over a value.

It might be easier to read this implementation if it leveraged those language constructs.

Improve handling of lists when exporting markdown

6607b6a

- Links in list items should get resolved to title + link (179135030) - Term lists shouldn't render with the word "term" in them (166128254)

jrturton requested a review from a team as a code owner June 11, 2026 13:49

d-ronnqvist requested changes Jun 11, 2026

View reviewed changes

d-ronnqvist reviewed Jun 11, 2026

View reviewed changes

Put term list updates in a separate branch / PR

1ed7d8e

d-ronnqvist reviewed Jun 12, 2026

View reviewed changes

d-ronnqvist requested changes Jun 12, 2026

View reviewed changes

d-ronnqvist mentioned this pull request Jun 12, 2026

Format term lists in markdown export #1544

Open

3 tasks

		These are some interesting links that are in ordered list items:

	mutating func convertSymbolLink(_ symbolLink: SymbolLink) -> (link: any InlineMarkup, abstract: (any Markup)?)? {
	private func convertSymbolLink(_ symbolLink: SymbolLink) -> (link: any InlineMarkup, abstract: (any Markup)?)? {


		mutating func visitLink(_ link: Link) {

		mutating func convertLink(_ link: Link) -> (link: Link, abstract: (any Markup)?) {

	mutating func convertLink(_ link: Link) -> (link: Link, abstract: (any Markup)?) {
	private func convertLink(_ link: Link) -> (link: Link, abstract: (any Markup)?) {

	mutating func convertListItem(_ item: ListItem) -> ListItem {
	private func convertListItem(_ item: ListItem) -> ListItem {

Conversation

jrturton commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Dependencies

Testing

Checklist

Uh oh!

d-ronnqvist left a comment

Choose a reason for hiding this comment

Uh oh!

d-ronnqvist commented Jun 11, 2026

Uh oh!

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

Updating existing tests

Uh oh!

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!

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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jrturton commented Jun 11, 2026 •

edited

Loading