Swift.org logo and link (alt 2)

.gitignore

@@ -9,3 +9,4 @@ Package.resolved
 **/*.docc/header.html
 **/*.docc/footer.html
 scripts/__pycache__/
+.playwright-cli/

.licenseignore

@@ -1,4 +1,5 @@
 **/*.gitkeep
 **/*.html
+**/*.svg
 **/Package.swift
 common/README

common/README

@@ -8,9 +8,19 @@ The common files need to be copied, or perhaps linked, into each of the DocC cat
 
 Both files are intentionally minimal:
 
-- `header.html` has no visible content. It's a reserved hook (DocC's
-  `custom-header` template) for a future documentation-version switcher —
-  add the switcher UI to the `#version-switcher` div when that lands.
+- `header.html` uses DocC's `custom-header` template hook to add a Swift logo
+  linking to swift.org to the masthead, between the sidebar-toggle control
+  and the page title. It targets the masthead rather than the Navigator
+  sidebar because the sidebar gets torn down and rebuilt once its data
+  loads (discarding anything inserted into its loading-skeleton state),
+  while the masthead mounts once and stays. The logo is appended inside
+  `.pre-title` rather than inserted as a sibling before `.nav-title`, since
+  swift-docc-render positions the title via the adjacent-sibling CSS rule
+  `.pre-title + .nav-title`, which needs them to stay adjacent. Being part
+  of the masthead rather than the sidebar, it stays visible regardless of
+  the sidebar's shown/hidden/drawer state. It also still reserves the
+  `#version-switcher` div for a future documentation-version switcher — add
+  the switcher UI there when that lands.
 - `footer.html` carries the copyright/trademark notice, the same legal links
   (License, Security, Privacy Policy, Cookies) swift.org's footer has, and
   an Adobe Analytics page-activation snippet mirroring swift.org's

common/header.html

@@ -9,3 +9,64 @@
 -->
 <!-- Reserved for a future documentation-version switcher. Intentionally empty until that exists. -->
 <div id="version-switcher"></div>
+
+<script>
+(function () {
+  // Sourced from developer.apple.com/swift/resources/images/swift_logo_color.svg,
+  // the official full-color Swift mark. Sized to 22x22 to match the space
+  // the previous mono glyph occupied in the masthead.
+  var LOGO_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 106.1 106.1" width="22" height="22" aria-hidden="true"><path fill="#f05138" d="m106.1 29.4c0-1.1 0-2.1 0-3.2-.1-2.3-.2-4.7-.6-7s-1.1-4.5-2.2-6.6-2.4-4-4.1-5.6c-1.7-1.7-3.6-3-5.6-4.1-2.1-1.1-4.3-1.8-6.6-2.2s-4.6-.6-7-.6c-1.1 0-2.1 0-3.2 0-1.3 0-2.5 0-3.8 0h-28.1-11.6c-1.3 0-2.5 0-3.8 0-1.1 0-2.1 0-3.2 0-.6 0-1.2 0-1.7.1-1.7.1-3.5.2-5.2.5s-3.4.8-5 1.4c-.5.2-1.1.5-1.6.7-1.6.8-3 1.8-4.4 2.9-.4.4-.9.8-1.3 1.2-1.7 1.7-3 3.6-4.1 5.6-1.1 2.1-1.8 4.3-2.2 6.6s-.5 4.6-.6 7v3.2 3.8 17.3 22.4 3.8 3.2c.1 2.3.2 4.7.6 7s1.1 4.5 2.2 6.6 2.4 4 4.1 5.6c1.7 1.7 3.6 3 5.6 4.1 2.1 1.1 4.3 1.8 6.6 2.2s4.6.6 7 .6h3.2 3.8 39.7 3.8 3.2c2.3-.1 4.7-.2 7-.6s4.5-1.1 6.6-2.2 4-2.4 5.6-4.1c1.7-1.7 3-3.6 4.1-5.6 1.1-2.1 1.8-4.3 2.2-6.6s.6-4.6.6-7c0-1.1 0-2.1 0-3.2 0-1.3 0-2.5 0-3.8v-39.7c-0-1.2-0-2.4-0-3.7z"/><path fill="#fff" d="m84 65.5c.1-.4.2-.8.3-1.2 4.4-17.5-6.3-38.3-24.5-49.2 8 10.8 11.5 23.9 8.4 35.3-.3 1-.6 2-1 3-.4-.3-.9-.6-1.6-.9 0 0-18.1-11.2-37.7-30.9-.5-.5 10.5 15.7 22.9 28.8-5.9-3.3-22.2-15.2-32.6-24.6 1.3 2.1 2.8 4.2 4.4 6.1 8.6 11 19.9 24.5 33.4 34.9-9.5 5.8-22.9 6.3-36.2 0-3.3-1.5-6.4-3.4-9.3-5.5 5.6 9 14.3 16.8 24.9 21.4 12.6 5.4 25.2 5.1 34.5.1s.1 0 .1-.1c.4-.2.8-.5 1.2-.7 4.5-2.3 13.3-4.6 18.1 4.6 1.4 2.1 3.9-9.9-5.3-21.1z"/></svg>';
+
+  // Appended inside `.pre-title` rather than inserted as a sibling before
+  // `.nav-title`: swift-docc-render positions the title via the CSS rule
+  // `.pre-title + .nav-title`, which needs them to stay adjacent siblings.
+  // This keeps that intact while still landing between the sidebar toggle
+  // and the title — and, being part of the masthead rather than the
+  // sidebar, it stays visible regardless of the sidebar's own
+  // shown/hidden/drawer state.
+  function insertLogoLink() {
+    var preTitle = document.querySelector('.pre-title');
+    if (!preTitle || preTitle.querySelector('.masthead-swift-logo')) {
+      return false;
+    }
+    var link = document.createElement('a');
+    link.href = 'https://www.swift.org';
+    link.className = 'masthead-swift-logo';
+    link.setAttribute('aria-label', 'Swift.org');
+    link.innerHTML = LOGO_SVG;
+    preTitle.appendChild(link);
+    return true;
+  }
+
+  // swift-docc-render hardcodes this text to the `documentation.title`
+  // locale string ("Documentation") in DocumentationTopic.vue — there's no
+  // theme-settings.json or DocC metadata hook for it, so it's overwritten
+  // here after render, the same way the logo above is inserted.
+  function relabelNavTitle() {
+    var navTitle = document.querySelector('.nav-title');
+    if (!navTitle || navTitle.textContent.trim() === 'Swift') {
+      return false;
+    }
+    navTitle.textContent = 'Swift';
+    return true;
+  }
+
+  // Styled on the main document, not this template's own shadow root: the
+  // masthead this targets lives outside this custom element's shadow tree,
+  // in the app's regular (light) DOM.
+  var style = document.createElement('style');
+  style.textContent = '.masthead-swift-logo{display:flex;align-items:center;padding-inline:8px;}';
+  document.head.appendChild(style);
+
+  function applyMastheadTweaks() {
+    var logoInserted = insertLogoLink();
+    var titleRelabeled = relabelNavTitle();
+    return logoInserted && titleRelabeled;
+  }
+
+  if (!applyMastheadTweaks()) {
+    var observer = new MutationObserver(applyMastheadTweaks);
+    observer.observe(document.body, { childList: true, subtree: true });
+  }
+})();
+</script>