feat: respect url normalization for toc

dotnet · Aug 2, 2023 · adb5614 · adb5614
1 parent a8d1438
commit adb5614
Show file tree

Hide file tree

Showing 3 changed files with 35 additions and 27 deletions.
diff --git a/docs/docs/template.md b/docs/docs/template.md
@@ -1,6 +1,6 @@
 # Template
 
-Template defines the appearance of the website. 
+Template defines the appearance of the website.
 
 Docfx ships several built-in templates. We recommend using the modern template that matches the look and feel of this site. It supports dark mode, more features, rich customization options and.
 
@@ -26,30 +26,31 @@ The easiest way of customizing the the appearance of pages is using [metadata](.
 
 # [Modern Template](#tab/modern)
 
-Name         | Type    | Description
-----------------------|---------|---------------------------
-`_appTitle`             | string  | A string append to every page title.
-`_appName`              | string  | The name of the site displayed after logo.
-`_appFooter`            | string  | The footer HTML.
-`_appLogoPath`          | string  | Path to the app logo.
-`_appLogoUrl`           | string  | URL for the app logo.
-`_appFaviconPath`       | string  | Favicon URL path.
-`_enableSearch`         | bool    | Whether to show the search box.
-`_noindex`              | bool    | Whether to include in search results
-`_disableContribution`  | bool    | Whether to show the _"Edit this page"_ button.
-`_gitContribute`        | object  | Defines the `repo` and `branch` property of git links.
-`_gitUrlPattern`        | string  | URL pattern of git links.
-`_disableNewTab`        | bool    | Whether to render external link indicator icons and open external links in a new tab.
-`_disableNextArticle`   | bool    | Whether to show the previous and next article link.
-`_disableTocFilter`     | bool    | Whether to show the table of content filter box.
-`_googleAnalyticsTagId` | string  | Enables Google Analytics web traffic analysis.
-`_lang`                  | string  | Primary language of the page. If unset, the `<html>` tag will not have `lang` property.
-`_layout`                | string  | Determines the layout of the page. Supported values are `landing` and `chromeless`.
+Name                      | Type    | Description
+--------------------------|---------|---------------------------
+`_appTitle`               | string  | A string append to every page title.
+`_appName`                | string  | The name of the site displayed after logo.
+`_appFooter`              | string  | The footer HTML.
+`_appLogoPath`            | string  | Path to the app logo.
+`_appLogoUrl`             | string  | URL for the app logo.
+`_appFaviconPath`         | string  | Favicon URL path.
+`_enableSearch`           | bool    | Whether to show the search box.
+`_noindex`                | bool    | Whether to include in search results
+`_disableContribution`    | bool    | Whether to show the _"Edit this page"_ button.
+`_gitContribute`          | object  | Defines the `repo` and `branch` property of git links.
+`_gitUrlPattern`          | string  | URL pattern of git links.
+`_disableNewTab`          | bool    | Whether to render external link indicator icons and open external links in a new tab.
+`_disableNextArticle`     | bool    | Whether to show the previous and next article link.
+`_disableTocFilter`       | bool    | Whether to show the table of content filter box.
+`_googleAnalyticsTagId`   | string  | Enables Google Analytics web traffic analysis.
+`_lang`                   | string  | Primary language of the page. If unset, the `<html>` tag will not have `lang` property.
+`_layout`                 | string  | Determines the layout of the page. Supported values are `landing` and `chromeless`.
+`_urlNormalizationActive` | bool    | Whether any url normalization rules are active. If unset, the default value is `false`.
 
 # [Default Template](#tab/default)
 
-Name         | Type    | Description
-----------------------|---------|---------------------------
+Name                    | Type    | Description
+------------------------|---------|---------------------------
 `_appTitle`             | string  | A string append to every page title.
 `_appName`              | string  | The name of the site displayed after logo.
 `_appFooter`            | string  | The footer HTML.
@@ -58,7 +59,7 @@ Name         | Type    | Description
 `_appFaviconPath`       | string  | Favicon URL path.
 `_enableSearch`         | bool    | Whether to show the search box.
 `_enableNewTab`         | bool    | Whether to open external links in a new tab.
-`_noindex`              | bool  | Whether to include in search results
+`_noindex`              | bool    | Whether to include in search results
 `_disableContribution`  | bool    | Whether to show the _"Improve this Doc"_ and _"View Source"_ buttons.
 `_gitContribute`        | object  | Defines the `repo` and `branch` property of git links.
 `_gitUrlPattern`        | string  | URL pattern of git links.
@@ -67,7 +68,7 @@ Name         | Type    | Description
 `_disableToc`           | bool    | Whether to show the TOC.
 `_disableAffix`         | bool    | Whether to show the right rail.
 `_googleAnalyticsTagId` | string  | Enables Google Analytics web traffic analysis.
-`_lang`                 | string | Primary language of the page. If unset, the `<html>` tag will not have `lang` property.
+`_lang`                 | string  | Primary language of the page. If unset, the `<html>` tag will not have `lang` property.
 
 ---
 

diff --git a/templates/modern/layout/_master.tmpl b/templates/modern/layout/_master.tmpl
@@ -24,6 +24,7 @@
       {{#_enableSearch}}<meta name="docfx:rel" content="{{_rel}}">{{/_enableSearch}}
       {{#_disableNewTab}}<meta name="docfx:disablenewtab" content="true">{{/_disableNewTab}}
       {{#_disableTocFilter}}<meta name="docfx:disabletocfilter" content="true">{{/_disableTocFilter}}
+      {{#_urlNormalizationActive}}<meta name="docfx:urlnormalizationactive" content="true">{{/_urlNormalizationActive}}
       {{#docurl}}<meta name="docfx:docurl" content="{{docurl}}">{{/docurl}}
     {{/redirect_url}}
   </head>
@@ -117,7 +118,7 @@
         {{^_disableNextArticle}}
         <div class="next-article d-print-none border-top" id="nextArticle"></div>
         {{/_disableNextArticle}}
-        
+
       </div>
 
       <div class="affix">
@@ -138,4 +139,4 @@
     </footer>
   </body>
   {{/redirect_url}}
-</html>
+</html>
diff --git a/templates/modern/src/toc.ts b/templates/modern/src/toc.ts
@@ -139,7 +139,13 @@ export async function renderToc(): Promise<TocNode[]> {
   }
 
   function normalizeUrlPath(url: { pathname: string }): string {
-    return url.pathname.replace(/\/index\.html$/gi, '/')
+    const urlNormalization = meta('docfx:urlnormalizationactive')
+
+    if (urlNormalization !== undefined && urlNormalization !== null && urlNormalization === 'true' && !url.pathname.endsWith('/index.html') && !url.pathname.endsWith('.html') && !url.pathname.endsWith('/')) {
+      return url.pathname + '.html'
+    } else {
+      return url.pathname.replace(/\/index\.html$/gi, '/')
+    }
   }
 }