Skip to content

Conversation

@jrturton
Copy link
Contributor

@jrturton jrturton commented Jan 5, 2026

  • Explanation: Adds experimental markdown output when converting a catalog, under the control of two new feature flags.
  • Scope: Adds a small amount of new public API and new internal types to process DocumentationNode instances to produce markdown-formatted exports.
  • GitHub Issue: LLM-accessible output #1301
  • Risk: Low. Existing behaviour is not changed unless the new feature flags are enabled.
  • Testing: All unit tests pass, multiple new unit tests added to cover new functionality
  • Reviewer: @d-ronnqvist
  • Original PR: Experimental markdown output #1303

jrturton and others added 2 commits January 5, 2026 09:43
* Add experimental markdown output flag and pass it through to the convert feature flags

* Initial export of Markdown from Article

* Initial processing of a type-level symbol

* Adds symbol declarations and article reference links

* Output tutorials to markdown

* Be smarter about removing indentation from within block directives

* Baseline for adding new tests for markdown output

* Basic test infrastructure for markdown output

* Adds symbol link tests to markdown output

* Tutoorial code rendering markdown tests

* Adding metadata to markdown output

* Include package source for markdown output test catalog

* Output metadata updates

* Adds default availability for modules to markdown export

* Move availability out of symbol and in to general metadata for markdown output

* Refactor markdown output so the final node type is standalone

* Add generated markdown flag to render node metadata

* Only include unavailable in markdown header if it is true

* Initial setup of manifest output, no references

* Output of manifest / relationships

* Manifest output format updates

* Remove member symbol relationship

* More compact availability, deal with metadata availability for symbols

* Update tests so all inputs are locally defined

* Remove print statements from unused visitors

* Added snippet handling

* Remove or _spi-hide new public API

* Remove or _spi-hide new public API (part 2)

* Prevent recursion when the abstract of a link contains a link and we are rendering links-with-abstracts

* Test and temporary fix for colspan issue swiftlang/swift-markdown#238

* Remove separate SwiftDocCMarkdownOutput target

* Bump swift-markdown, remove temporary bug fix

* Updates to handle removed bundle parameter

* Extract common writer code into a helper function

* Clarify use of article.md in test catalog

* Deal with internal links with anchor tags

* Deal with unresolved symbol links

* Updates to improve public API / clarity of MarkdownOutputNode

* Improve public API of manifest, sort contents before writing to prevent unneccessary diffs on re-run

* Don't use unstructured `Data` for WritableMarkdownOutputNode

* Reduce public SPI surface around markdown writing

* Make relationship subtype a specific type rather than a string

* Make it clear that path component is a fallback title, harden linked list rendering

* Add todos and missing tests

* Move markdown output types from public SPI to package

* don't include scheme or host in documentation links

* Reformat multi-condition if statements

* remove whitespace-only change

* Remove unused declaration

* Remove redundant return types

* Remove MarkdownOutputNodeTranslator

* Add TODO for alternate declarations

* Add TODO for structural review

* Add stacks todo, set writable type back to package

* uri -> identifier

* Use RelationshipsGroup.Kind instead of creating a mirror type

* Lower access level of manifest, remove children method

* Restrict package level declarations to those actually used at package level

* Merging main

---------

Co-authored-by: Richard Turton <[email protected]>
@jrturton jrturton requested a review from franklinsch January 5, 2026 09:56
@d-ronnqvist
Copy link
Contributor

Is that scope description correct? IIRC the original PR omitted the public API.

@d-ronnqvist
Copy link
Contributor

Also, the original PR wasn't approved by Franklin, so please remove that incorrect information from the description

@jrturton
Copy link
Contributor Author

jrturton commented Jan 5, 2026

The new feature flags are public, and there were a couple of public types that were modified to add Sendable conformance. None of the rest of the changes are public, but I didn't want to say "no public API changes".

The wording of the PR template led me to assume I should put appropriate reviewers on there, not the people who reviewed the original PR, sorry. Will update.

@franklinsch
Copy link
Contributor

@swift-ci please test

@franklinsch
Copy link
Contributor

I triggered cross-repo testing here: swiftlang/swift#86317

@franklinsch
Copy link
Contributor

smoke tests have passed in the cross-repo testing

@franklinsch franklinsch merged commit da96357 into swiftlang:release/6.3 Jan 9, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants