feat: PDF download button (#9351)

Author: yufeih

docs/docfx.json

@@ -32,7 +32,8 @@
       "_appTitle": "docfx",
       "_appName": "docfx",
       "_appFooter": "<span>Supported by the <a href=\"https://dotnetfoundation.org\">.NET Foundation</a>. Made with <a href=\"https://dotnet.github.io/docfx\">docfx</a></span>",
-      "_googleAnalyticsTagId": "G-Q5N6XJHEX5"
+      "_googleAnalyticsTagId": "G-Q5N6XJHEX5",
+      "pdf": true
     },
     "markdownEngineProperties": {
       "alerts": {

templates/default(zh-cn)/token.json

@@ -58,5 +58,6 @@
   "themeDark": "夜晚",
   "themeAuto": "自动",
   "changeTheme": "切换主题",
-  "copy": "复制"
+  "copy": "复制",
+  "downloadPdf": "下载 PDF"
 }

templates/default/token.json

@@ -68,5 +68,6 @@
   "themeDark": "Dark",
   "themeAuto": "Auto",
   "changeTheme": "Change theme",
-  "copy": "Copy"
+  "copy": "Copy",
+  "downloadPdf": "Download PDF"
 }

templates/modern/layout/_master.tmpl

@@ -35,6 +35,7 @@
       <meta name="loc:themeAuto" content="{{__global.themeAuto}}">
       <meta name="loc:changeTheme" content="{{__global.changeTheme}}">
       <meta name="loc:copy" content="{{__global.copy}}">
+      <meta name="loc:downloadPdf" content="{{__global.downloadPdf}}">
     {{/redirect_url}}
   </head>
 
@@ -135,7 +136,7 @@
     <div class="container-xxl search-results" id="search-results"></div>
     {{/_enableSearch}}
 
-    <footer class="border-top">
+    <footer class="border-top text-secondary">
       <div class="container-xxl">
         <div class="flex-fill">
           {{{_appFooter}}}{{^_appFooter}}<span>Made with <a href="https://dotnet.github.io/docfx">docfx</a></span>{{/_appFooter}}

templates/modern/src/layout.scss

@@ -6,7 +6,7 @@
 $header-height: 60px;
 $footer-height: 60px;
 $main-padding-top: 1.6rem;
-$main-padding-bottom: 4rem;
+$main-padding-bottom: 2rem;
 
 // Makes a div sticky to top
 @mixin sticky-top {
@@ -53,6 +53,7 @@ body[data-layout="landing"] {
   }
 
   >footer {
+    font-size: 14px;
     padding: 1rem 0;
     height: $footer-height;
 
@@ -121,8 +122,7 @@ body[data-layout="landing"] {
         >.toc-offcanvas {
           flex: .35;
           display: block;
-          overflow-x: hidden;
-          overflow-y: auto;
+          overflow: hidden;
           max-width: 360px;
           max-height: calc(100vh - $header-height - $main-padding-top);
 
@@ -131,9 +131,15 @@ body[data-layout="landing"] {
           @include media-breakpoint-down(md) {
             flex: 0;
           }
+
+          .offcanvas-start, .offcanvas-body {
+            height: 100%;
+          }
         }
 
         >.content {
+          display: flex;
+          flex-direction: column;
           flex: 1;
           min-width: 0;
           margin: 0 3rem;
@@ -146,6 +152,10 @@ body[data-layout="landing"] {
             min-height: 40px;
           }
 
+          article {
+            flex: 1;
+          }
+
           >.contribution,
           >.next-article {
             display: flex;

templates/modern/src/toc.scss

@@ -8,6 +8,9 @@ $expand-stub-width: .85rem;
 .toc {
   min-width: 0;
   width: 100%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
 
   ul {
     font-size: 14px;
@@ -72,7 +75,7 @@ $expand-stub-width: .85rem;
     display: flex;
     position: relative;
     align-items: center;
-    margin-bottom: 1rem;
+    margin-bottom: .5rem;
 
     >i.bi {
       position: absolute;
@@ -89,4 +92,15 @@ $expand-stub-width: .85rem;
     font-size: .9em;
     color: $secondary;
   }
+  
+  a.pdf-link {
+    @include underline-on-hover;
+
+    &::before {
+      content: "\F756";
+      display: inline-block;
+
+      @include adjust-icon;
+    }
+  }
 }

templates/modern/src/toc.ts

@@ -24,7 +24,7 @@ export async function renderToc(): Promise<TocNode[]> {
   const disableTocFilter = meta('docfx:disabletocfilter') === 'true'
 
   const tocUrl = new URL(tocrel.replace(/.html$/gi, '.json'), window.location.href)
-  const { items } = await (await fetch(tocUrl)).json()
+  const { items, pdf, pdfFileName } = await (await fetch(tocUrl)).json()
 
   const tocFilterUrl = disableTocFilter ? '' : (localStorage?.getItem('tocFilterUrl') || '')
   let tocFilter = disableTocFilter ? '' : (localStorage?.getItem('tocFilter') || '')
@@ -92,7 +92,10 @@ export async function renderToc(): Promise<TocNode[]> {
   }
 
   function renderToc() {
-    render(html`${renderTocFilter()} ${renderTocNodes(items) || renderNoFilterResult()}`, tocContainer)
+    render(html`
+      ${renderTocFilter()} 
+      <div class="flex-fill overflow-y-auto">${renderTocNodes(items) || renderNoFilterResult()}</div>
+      ${renderDownloadPdf()}`, tocContainer)
   }
 
   function renderTocNodes(nodes: TocNode[]): TemplateResult {
@@ -150,6 +153,10 @@ export async function renderToc(): Promise<TocNode[]> {
     return tocFilter === '' ? null : html`<div class='no-result'>${loc('searchNoResults', { query: tocFilter })}</div>`
   }
 
+  function renderDownloadPdf(): TemplateResult {
+    return pdf ? html`<div class="py-2 mb-md-4"><a class="pdf-link" href="${pdfFileName || 'toc.pdf'}">${loc('downloadPdf')}</a></div>` : null
+  }
+
   function normalizeUrlPath(url: { pathname: string }): string {
     return url.pathname.replace(/\/index\.html$/gi, '/')
   }

test/docfx.Snapshot.Tests/SamplesTest.CSharp/api/CSharp10.ConstantInterpolatedStrings.html.view.verified.json

@@ -1079,6 +1079,7 @@
     "themeAuto": "Auto",
     "changeTheme": "Change theme",
     "copy": "Copy",
+    "downloadPdf": "Download PDF",
     "_shared": {}
   },
   "yamlmime": "ManagedReference",

test/docfx.Snapshot.Tests/SamplesTest.CSharp/api/CSharp10.Issue7737.html.view.verified.json

@@ -809,6 +809,7 @@
     "themeAuto": "Auto",
     "changeTheme": "Change theme",
     "copy": "Copy",
+    "downloadPdf": "Download PDF",
     "_shared": {}
   },
   "yamlmime": "ManagedReference",

test/docfx.Snapshot.Tests/SamplesTest.CSharp/api/CSharp10.ParameterlessStructConstructors.html.view.verified.json

@@ -1214,6 +1214,7 @@
     "themeAuto": "Auto",
     "changeTheme": "Change theme",
     "copy": "Copy",
+    "downloadPdf": "Download PDF",
     "_shared": {}
   },
   "yamlmime": "ManagedReference",