Match the documentation breadcrumb to the board's breadcrumb

controller/documentation_helper.php

@@ -24,6 +24,12 @@ class documentation_helper
 {
 	const COOKIE_NAME = 'phpbb_docs_lang';
 
+	/** Character Hugo's breadcrumb puts before its home link. */
+	const HUGO_HOME_GLYPH = '⌂';
+
+	/** Font Awesome icon shown instead. */
+	const BREADCRUMB_HOME_ICON = 'fa-info-circle';
+
 	/**
 	 * The one top-level section name the developer docs build produces
 	 * (see phpbbdocs_hugo_devdocs.sh) — the sole boundary between
@@ -858,6 +864,7 @@ protected function extract_fragments($file, $lang, $path, array $allowed_section
 			{
 				$switcher->parentNode->removeChild($switcher);
 			}
+			$this->use_breadcrumb_home_icon($breadcrumb_node);
 			$this->rewrite_absolute_links($breadcrumb_node);
 		}
 		$this->process_images($article_node, $lang, $path);
@@ -871,6 +878,30 @@ protected function extract_fragments($file, $lang, $path, array $allowed_section
 		);
 	}
 
+	/**
+	 * Replaces the small "⌂" character Hugo puts before the breadcrumb's
+	 * home link with a Font Awesome icon, sized like the board's own
+	 * breadcrumb icon.
+	 *
+	 * @param \DOMNode $breadcrumb_node
+	 * @return void
+	 */
+	protected function use_breadcrumb_home_icon(\DOMNode $breadcrumb_node)
+	{
+		$xpath = new \DOMXPath($breadcrumb_node->ownerDocument);
+		$text = $xpath->query('.//a[1]/text()[1]', $breadcrumb_node)->item(0);
+		if ($text === null || strpos(ltrim($text->nodeValue), self::HUGO_HOME_GLYPH) !== 0)
+		{
+			return;
+		}
+
+		$text->nodeValue = ltrim(substr(ltrim($text->nodeValue), strlen(self::HUGO_HOME_GLYPH)));
+		$icon = $breadcrumb_node->ownerDocument->createElement('i');
+		$icon->setAttribute('class', 'icon ' . self::BREADCRUMB_HOME_ICON . ' fa-fw');
+		$icon->setAttribute('aria-hidden', 'true');
+		$text->parentNode->insertBefore($icon, $text);
+	}
+
 	/**
 	 * Removes .docs-tree-section blocks the current user isn't allowed to
 	 * see, identified by the section segment of each section link's

styles/all/theme/documentation.css

@@ -4,7 +4,16 @@
 	justify-content: space-between;
 	flex-wrap: wrap;
 	gap: 10px;
+	/* With phpBB's 4px .page-body margin, 5px between the navbar and the line. */
+	padding-top: 1px;
 	margin-bottom: 10px;
+	/* Same size as the board's own breadcrumbs (prosilver's ul.linklist > li). */
+	font-size: 1.1em;
+}
+
+/* Bold like the board's breadcrumb links; the language picker keeps bold for the current language only. */
+.documentation-breadcrumb .utility-bar {
+	font-weight: bold;
 }
 
 .documentation-language-picker a {

tests/controller/documentation_helper_test.php

@@ -331,14 +331,17 @@ public function test_get_available_languages_reflects_the_build()
 
 	public function test_imported_language_switcher_is_removed_but_labels_remain_available()
 	{
-		file_put_contents($this->docs_root . '/da/index.html', '<html><body>
-			<div class="utility-bar"><a href="/da/">Documentation home</a>
+		// Hugo pages declare UTF-8, which DOMDocument needs to read the ⌂ correctly.
+		file_put_contents($this->docs_root . '/da/index.html', '<html><head><meta charset="utf-8"></head><body>
+			<div class="utility-bar"><a href="/da/">⌂ Documentation home</a>
 			<div class="language-switcher"><a href="/da/" lang="da">Dansk</a><a href="/en/" lang="en">English</a></div></div>
 			<article class="docs-article">Article</article></body></html>');
 		$helper = $this->get_helper();
 		$result = $helper->resolve_and_load('da', '');
 		$this->assertStringContainsString('Documentation home', $result['breadcrumb_html']);
 		$this->assertStringNotContainsString('language-switcher', $result['breadcrumb_html']);
+		$this->assertStringContainsString('<i class="icon fa-info-circle fa-fw" aria-hidden="true"></i>Documentation home', $result['breadcrumb_html']);
+		$this->assertStringNotContainsString('⌂', $result['breadcrumb_html']);
 		$this->assertStringNotContainsString('English', $result['breadcrumb_html']);
 		$this->assertSame(array('da' => 'Dansk', 'en' => 'English'), $helper->get_language_labels());
 	}