Add a helper function for rendering page breadcrumbs as HTML #1378
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
Author
|
@swift-ci please test |
rdar://163326857
d-ronnqvist
force-pushed
the
output-html-breadcrumbs
branch
from
134fe56 to
f3cf42a
Compare
Contributor
Author
|
@swift-ci please test |
mayaepps
approved these changes
Dec 4, 2025
| return switch goal { | ||
| case .richness: | ||
| if names.count == 1 { | ||
| [.text(names.first!.value)] |
Contributor
There was a problem hiding this comment.
Why do we want this behavior if there is only one language-specific name? If there is a language-specific name, even if there is only one, wouldn't we want to go through the logic in the else block that applies a "class" attribute (which I assume is used for formatting)?
Contributor
Author
There was a problem hiding this comment.
That's a good question that I don't know if I've written down the answer to anywhere.
The idea is that the language specific elements would have classes like "swift-only" or "occ-only" that can be shown or hidden through very small CSS changes. For example, consider this HTML that represents a link to a method with different names in Swift and Objective-C:
<a href=../somemethod(with:and:)/index.html>
<code class="swift-only">someMethod(with:and:)</code>
<code class="occ-only">someMethodWithFirst:AndSecond:</code>
</a>If we add this CSS to the page:
.swift-only {}
.occ-only {
display: none;
}the rendered page will only display the Swift title for that link. If we flip the CSS, then the rendered page will only display the Objective-C title for that link.
If the symbol has the same title on both languages, or is only available in a single language,then it's unnecessary to have 2 <code> elements, and the HTML can be simplified to just:
<a href=../somemethod(with:and:)/index.html>
<code>someMethod(with:and:)</code>
</a>
Co-authored-by: Joseph Heck <j_heck@apple.com>
Contributor
Author
|
@swift-ci please test |
This was referenced Dec 5, 2025
d-ronnqvist
added a commit
to d-ronnqvist/swift-docc
that referenced
this pull request
Dec 17, 2025
…ng#1378) * Add a helper function for rendering page breadcrumbs as HTML rdar://163326857 * Apply wording suggestion in documentation comment Co-authored-by: Joseph Heck <j_heck@apple.com> --------- Co-authored-by: Joseph Heck <j_heck@apple.com>
d-ronnqvist
added a commit
that referenced
this pull request
Dec 17, 2025
…1402) * Add a new target for rendering Markdown content into static HTML (#1369) * Add a new target for rendering content into static HTML rdar://163326857 * Include documentation comments with examples for the various `visit(_:)` methods. * Document what a `LinkedAsset` represents * Add code comments to explain how the inline HTML markup is parsed * Don't lowercase anchors for self-referencing headings * Avoid nested scopes when switching over names * Add a code comment about what an "autolink" is * Add a helper function for rendering availability information as HTML (#1376) rdar://163326857 * Add a helper function for rendering page breadcrumbs as HTML (#1378) * Add a helper function for rendering page breadcrumbs as HTML rdar://163326857 * Apply wording suggestion in documentation comment Co-authored-by: Joseph Heck <j_heck@apple.com> --------- Co-authored-by: Joseph Heck <j_heck@apple.com> * Add a helper function for rendering a parameters section as HTML (#1377) * Add a helper function for rendering a parameters section as HTML rdar://163326857 * Apply wording suggestions in documentation comments Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> Co-authored-by: Joseph Heck <j_heck@apple.com> * Add TODO comment about a debug assertion for the parameter name order --------- Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> Co-authored-by: Joseph Heck <j_heck@apple.com> * Add tests for parsing of inline HTML when rendering markdown as HTML (#1379) * Add test about parsing inline HTML except for comments * Extract inner HTML parsing code into a private function * Fix minor spelling in code comment Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> --------- Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> * Add a helper function for rendering a returns sections as HTML (#1381) * Add a helper function for rendering a returns sections as HTML rdar://163326857 * Minor phrasing updates to the parameter section helper's documentation * Add new source file to Windows CMake file list * Correct grammar in documentation comments Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> --------- Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> * Add a helper function for rendering symbol declarations as HTML (#1384) * Add a helper function for rendering symbol declarations as HTML rdar://163326857 * Add code comments to describe why the concise declaration: - Only includes the primary language - Joins the declaration fragments into a single string * Add a helper function for rendering a Topics/SeeAlso section as HTML (#1382) * Add a helper function for rendering a Topics/SeeAlso section as HTML rdar://163326857 * Add more code comments and internal documentation comments * Very slightly correct the test data * Minimally integrate per-page HTML content into each "index.html" file (#1383) * Minimally integrate per-page HTML content into each "index.html" file rdar://163326857 * Extract some common code into private helpers * Move a few common checks into the new private helpers * Add a helper function for rendering a discussion section as HTML (#1388) * Add a helper function for rendering a discussion section as HTML rdar://163326857 * Integrate the discussion section in the HTML renderer * Include Mentioned In and Relationships sections in the HTML output (#1391) * Include more content in the HTML output (#1390) * Include more page content in the HTML output * Also add deprecation summaries to the HTML output --------- Co-authored-by: Joseph Heck <j_heck@apple.com> Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Bug/issue #, if applicable: rdar://163326857
Summary
This is another slice of #1366
It adds a helper function to the
DocCHTML/MarkdownRendererto render page breadcrumbs as HTMLDependencies
None.
Testing
Nothing in particular for this PR. It only adds an internal helper function. See #1366 for how it eventually does get used.
Checklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
./bin/testscript and it succeeded