Skip to content

Add support for Mermaid charts to README files #3499

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 7 commits into from
Nov 15, 2024
Merged

Add support for Mermaid charts to README files #3499

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
64c0c38
fixed database script temporary, added mermaid
leogdion Oct 24, 2024
5c154d3
fixing theme switching
leogdion Nov 4, 2024
619619f
adding code comments
leogdion Nov 4, 2024
cd165a5
Update Makefile
leogdion Nov 4, 2024
cd9474f
What a rabbit hole that was!
daveverwer Nov 14, 2024
937533b
This is a better way to hide the loading indicator.
daveverwer Nov 15, 2024
775ec45
Snapshots.
daveverwer Nov 15, 2024
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
33 changes: 33 additions & 0 deletions FrontEnd/scripts/controllers/readme_controller.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,41 @@
// limitations under the License.

import { Controller } from '@hotwired/stimulus'
import mermaid from 'mermaid'

export class ReadmeController extends Controller {
frameLoaded() {
this.navigateToAnchorFromLocation()
this.renderMermaidDiagrams()
}

async renderMermaidDiagrams() {
// Replace all Mermaid chart sources with rendered diagrams.
const mermaidSectionElements = document.querySelectorAll('section[data-type="mermaid"]')
for (const [index, mermaidSectionElement] of Array.from(mermaidSectionElements).entries()) {
// No need to parse the JSON, the chart source is in a `data-plain` attribute.
const mermaidDataElement = mermaidSectionElement.querySelector('[data-plain]')
if (!mermaidDataElement) continue
const chartDefinition = mermaidDataElement.getAttribute('data-plain')
if (!chartDefinition) continue

// Make a container with *both* light and dark charts.
const chartContainer = document.createElement('div')
chartContainer.classList.add('mermaid-chart')
mermaidDataElement.appendChild(chartContainer)

// The documentation says not to call `initialize` more than once. That said, it's
// the only way to switch themes and therefore the only way to get this working.
mermaid.initialize({ theme: 'default', nodeSpacing: 50, rankSpacing: 50, curve: 'basis' })
const lightRenderResult = await mermaid.render(`mermaid-chart-light-${index}`, chartDefinition)
chartContainer.insertAdjacentHTML('beforeend', lightRenderResult.svg)

mermaid.initialize({ theme: 'dark', nodeSpacing: 50, rankSpacing: 50, curve: 'basis' })
const darkRenderResult = await mermaid.render(`mermaid-chart-dark-${index}`, chartDefinition)
chartContainer.insertAdjacentHTML('beforeend', darkRenderResult.svg)
}
}

navigateToAnchorFromLocation() {
// If the browser has an anchor in the URL that may be inside the README then
// we should attempt to scroll it into view once the README is loaded.
Expand Down
25 changes: 25 additions & 0 deletions FrontEnd/styles/readme.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,31 @@
.markdown-alert-caution {
color: var(--mid-red);
}

.mermaid-chart {
display: flex;
justify-content: center;
padding: 30px 0;
}

section[data-type='mermaid'] {
pre,
.js-render-enrichment-loader {
display: none;
}

@media (prefers-color-scheme: light) {
[id^='mermaid-chart-dark'] {
display: none;
}
}

@media (prefers-color-scheme: dark) {
[id^='mermaid-chart-light'] {
display: none;
}
}
}
}

g-emoji {
Expand Down
2 changes: 1 addition & 1 deletion Sources/App/Views/PackageController/PackageShow+View.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -327,7 +327,7 @@ extension PackageShow {
.value(model.repositoryName),
.readme).relativeURL(),
.data(named: "controller", value: "readme"),
.data(named: "action", value: "turbo:frame-load->readme#navigateToAnchorFromLocation"),
.data(named: "action", value: "turbo:frame-load->readme#frameLoaded"),
.div(.spinner())
)
}
Expand Down
2 changes: 1 addition & 1 deletion Tests/AppTests/__Snapshots__/WebpageSnapshotTests/test_PackageShowView.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,7 +359,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
2 changes: 1 addition & 1 deletion ...apshots__/WebpageSnapshotTests/test_PackageShowView_app_store_incompatible_license.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,7 +359,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
2 changes: 1 addition & 1 deletion Tests/AppTests/__Snapshots__/WebpageSnapshotTests/test_PackageShowView_binary_targets.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -363,7 +363,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
2 changes: 1 addition & 1 deletion ...napshots__/WebpageSnapshotTests/test_PackageShowView_canonicalURL_noImageSnapshots.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -356,7 +356,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/owner/repo/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/owner/repo/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
2 changes: 1 addition & 1 deletion .../AppTests/__Snapshots__/WebpageSnapshotTests/test_PackageShowView_customCollection.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -362,7 +362,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
2 changes: 1 addition & 1 deletion Tests/AppTests/__Snapshots__/WebpageSnapshotTests/test_PackageShowView_emoji_summary.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -356,7 +356,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
2 changes: 1 addition & 1 deletion Tests/AppTests/__Snapshots__/WebpageSnapshotTests/test_PackageShowView_few_keywords.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -387,7 +387,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
2 changes: 1 addition & 1 deletion Tests/AppTests/__Snapshots__/WebpageSnapshotTests/test_PackageShowView_many_keywords.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -562,7 +562,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
2 changes: 1 addition & 1 deletion ...pTests/__Snapshots__/WebpageSnapshotTests/test_PackageShowView_no_authors_activity.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -351,7 +351,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
2 changes: 1 addition & 1 deletion Tests/AppTests/__Snapshots__/WebpageSnapshotTests/test_PackageShowView_no_builds.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,7 +242,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
2 changes: 1 addition & 1 deletion Tests/AppTests/__Snapshots__/WebpageSnapshotTests/test_PackageShowView_no_license.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,7 +359,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
2 changes: 1 addition & 1 deletion ...pTests/__Snapshots__/WebpageSnapshotTests/test_PackageShowView_open_source_license.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -358,7 +358,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
2 changes: 1 addition & 1 deletion Tests/AppTests/__Snapshots__/WebpageSnapshotTests/test_PackageShowView_other_license.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,7 +359,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
2 changes: 1 addition & 1 deletion ...AppTests/__Snapshots__/WebpageSnapshotTests/test_PackageShowView_single_row_tables.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -294,7 +294,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
2 changes: 1 addition & 1 deletion ...ts/__Snapshots__/WebpageSnapshotTests/test_PackageShowView_withPackageFundingLinks.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -364,7 +364,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
2 changes: 1 addition & 1 deletion ...ts/__Snapshots__/WebpageSnapshotTests/test_PackageShowView_with_documentation_link.1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,7 +359,7 @@ <h3>Compatibility</h3>
</ul>
</nav>
<section data-tab-bar-target="content">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#navigateToAnchorFromLocation">
<turbo-frame id="readme_content" src="/Alamo/Alamofire/readme" data-controller="readme" data-action="turbo:frame-load->readme#frameLoaded">
<div>
<div class="spinner">
<div class="rect1"></div>
Expand Down
Loading
Loading