From 59a77f82cac45cddd15a45c35483f4428b1b4278 Mon Sep 17 00:00:00 2001 From: Yufei Huang Date: Tue, 14 Mar 2023 15:28:28 +0800 Subject: [PATCH] feat: update docfx to use modern template --- docs/docfx.json | 1 + docs/template/dashboard.html.tmpl | 123 ++++++++--------------- docs/template/index.html.tmpl | 20 ---- docs/template/layout/_master.tmpl | 57 ----------- docs/template/styles/main.css | 145 +-------------------------- templates/build.js | 3 +- templates/modern/layout/_master.tmpl | 1 + templates/modern/src/docfx.scss | 1 + templates/modern/src/docfx.ts | 5 +- templates/modern/src/layout.scss | 55 +++++----- templates/modern/src/nav.ts | 23 +++++ templates/modern/src/theme.ts | 51 +++++----- templates/modern/src/toc.ts | 6 +- 13 files changed, 133 insertions(+), 358 deletions(-) delete mode 100644 docs/template/index.html.tmpl delete mode 100644 docs/template/layout/_master.tmpl diff --git a/docs/docfx.json b/docs/docfx.json index aedff16d181..39fc962cc70 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -37,6 +37,7 @@ "dest": "_site", "template": [ "default", + "modern", "template" ] } diff --git a/docs/template/dashboard.html.tmpl b/docs/template/dashboard.html.tmpl index f09ad6d8922..73993916a9e 100644 --- a/docs/template/dashboard.html.tmpl +++ b/docs/template/dashboard.html.tmpl @@ -1,88 +1,47 @@ {{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}} -{{!include(/^styles/.*/)}} -{{!include(/^fonts/.*/)}} -{{!include(favicon.ico)}} -{{!include(logo.svg)}} - - - - {{>partials/head}} - - -
-
- {{>partials/navbar}} - {{>partials/breadcrumb}} -
-
- {{>partials/toc}} -
-

{{title}}

- - Improve this Doc - - {{#items.Length}} -
    - {{#items}} -
  • -
    - -
    - {{name}} -

    {{{description}}}

    - {{#usage}} -
      - {{#init}} -
    • Init:{{init}}
      • - {{/init}} - {{#command}} -
    • In command:{{command}}
      • - {{/command}} - {{#config}} -
    • In docfx.json:{{config}}
      • - {{/config}} -
    - {{/usage}} -
    • - {{/items}} -
- {{/items.Length}} -
-
- {{>partials/footer}} -
- {{>partials/scripts}} - - \ No newline at end of file + diff --git a/docs/template/index.html.tmpl b/docs/template/index.html.tmpl deleted file mode 100644 index 23c520417f0..00000000000 --- a/docs/template/index.html.tmpl +++ /dev/null @@ -1,20 +0,0 @@ -{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}} -{{!include(/^styles/.*/)}} -{{!include(/^fonts/.*/)}} -{{!include(favicon.ico)}} -{{!include(logo.svg)}} - - - - {{>partials/head}} - -
-
- {{>partials/navbar}} -
- {{{conceptual}}} - {{>partials/footer}} -
- {{>partials/scripts}} - - \ No newline at end of file diff --git a/docs/template/layout/_master.tmpl b/docs/template/layout/_master.tmpl deleted file mode 100644 index 4015c9c00f8..00000000000 --- a/docs/template/layout/_master.tmpl +++ /dev/null @@ -1,57 +0,0 @@ -{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}} -{{!include(/^styles/.*/)}} -{{!include(/^fonts/.*/)}} -{{!include(favicon.ico)}} -{{!include(logo.svg)}} -{{!include(search-stopwords.json)}} - - - - {{>partials/head}} - {{^redirect_url}} - -
-
- {{^_disableNavbar}} - {{>partials/navbar}} - {{/_disableNavbar}} - {{^_disableBreadcrumb}} - {{>partials/breadcrumb}} - {{/_disableBreadcrumb}} -
- {{#_enableSearch}} -
- {{>partials/searchResults}} -
- {{/_enableSearch}} -
- {{^_disableToc}} - {{>partials/toc}} -
- {{/_disableToc}} - {{#_disableToc}} -
- {{/_disableToc}} - {{#_disableAffix}} -
- {{/_disableAffix}} - {{^_disableAffix}} -
- {{/_disableAffix}} -
- {{!body}} -
-
- {{^_disableAffix}} - {{>partials/affix}} - {{/_disableAffix}} -
-
- {{^_disableFooter}} - {{>partials/footer}} - {{/_disableFooter}} -
- {{>partials/scripts}} - - {{/redirect_url}} - diff --git a/docs/template/styles/main.css b/docs/template/styles/main.css index 0588bba0e96..cdb063c229c 100644 --- a/docs/template/styles/main.css +++ b/docs/template/styles/main.css @@ -1,145 +1,6 @@ /* Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT License. See License.txt in the project root for license information. */ -/* Colors */ -button, a, .btn-primary { - color: #47A7A0; -} -.btn-primary:hover, .btn-primary:focus, button:hover, button:focus, a:hover, a:focus, .toc .nav > li.active > a:hover, .toc .nav > li.active > a:focus, .toc .nav > li > a:hover, .toc .nav > li > a:focus { - color: #6E8B60; -} -.btn-primary.disable, .btn-primary.disable:hover, a.disable, a.disable:hover{ - color: #90ABB9; -} -.hero { - color: #C1D38B; - background-color: #385361; - background-image: -webkit-gradient(linear,left bottom,right top,color-stop(0%,#000),color-stop(100%,#385361)); - background-image: -webkit-linear-gradient(45deg,#000 0,#385361 100%); - background-image: -moz-linear-gradient(45deg,#000 0,#385361 100%); - background-image: -ms-linear-gradient(45deg,#000 0,#385361 100%); - background-image: -o-linear-gradient(45deg,#000 0,#385361 100%); - background-image: linear-gradient(45deg,#000 0,#385361 100%); - filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#000', endColorstr='#385361', GradientType=1); -} -.hero strong { - color: #e7e7e7; -} -.buttons-unit .button { - color: #fff; - background: #6E8B60; -} -.buttons-unit .button:active { - background: #A27865; -} -.toc .nav > li.active > a, .affix ul > li.active > a, .affix ul > li.active > a:before { - color: #6E8B60 -} -.btn-primary { - background: #385361; - color: #8BFEB4; -} - -.affix ul > li > a:before { - color: #cccccc; -} -.toc .nav > li > a, .affix ul > li > a, .affix ul > li > a:hover { - color: #666666; -} - -.counter-key-section{ - border: 2px solid #6E8B60; - -webkit-border-image-source: -webkit-gradient(linear, left, right, color-stop(0%, rgba(0, 0, 0, 0)), color-stop(50%, #385361), color-stop(100%, rgba(0, 0, 0, 0))); - -webkit-border-image-source: -webkit-linear-gradient(90deg, rgba(0, 0, 0, 0), #385361 50%, rgba(0, 0, 0, 0)); - -moz-border-image-source: -moz-linear-gradient(90deg, rgba(0, 0, 0, 0), #385361 50%, rgba(0, 0, 0, 0)); - -ms-border-image-source: -ms-linear-gradient(90deg, rgba(0, 0, 0, 0), #385361 50%, rgba(0, 0, 0, 0)); - -o-border-image-source: -o-linear-gradient(90deg, rgba(0, 0, 0, 0), #385361 50%, rgba(0, 0, 0, 0)); - border-image-source: linear-gradient(90deg, rgba(0, 0, 0, 0), #385361 50%, rgba(0, 0, 0, 0)); - border-image-slice: 1; -} - -/* End Colors */ - -.value-prop-heading { - font-size: 24px; -} - -#vp-container{ - margin-top: 30px; -} - -.hero { - height: 350px; - margin-top: 50px; - padding-top: 50px; - font-weight: 300; - text-align: center; -} -.key-section{ - padding: 30px 0; -} - -.key-section .glyphicon, .counter-key-section .glyphicon { - font-size: 4em; - display: table-cell; - vertical-align: middle; -} -.glyphicon { - margin-right: 10px; - font-size: 16px; -} - -.key-section section, .counter-key-section section { - display: table-cell; - padding-left: 20px; -} - -.key-section section p, .counter-key-section section p { - text-align: initial; -} - -.counter-key-section{ - padding: 30px 0; -} -.buttons-unit-small{ - font-size: 16px; -} -.version-link, .github-link{ - margin: 5px; -} -.hero strong { - font-weight: 400; - font-family: Rockwell; -} -.hero .text { - font-size: 64px; - text-align: center; -} -.hero .minitext { - font-size: 20px; - text-align: center; - font-family: Candara; -} -.buttons-unit { - margin-top: 60px; - text-align: center; -} -.hero .button { - border-radius: 4px; - padding: 8px 16px; - margin: 0 12px; - box-shadow: 1px 3px 3px rgba(0,0,0,0.3); -} -.buttons-unit .button { - font-size: 24px; -} - -@media only screen and (max-width: 768px) { - .hero { - height: 500px; - margin-top: 0px; - } - .hero .button { - display: block; - margin: 12px; - } +/* Checkout https://getbootstrap.com/docs/5.3/customize/color/ for more customization options */ +html { + --bs-link-color-rgb: 66, 184, 131 } \ No newline at end of file diff --git a/templates/build.js b/templates/build.js index 50a4eb92282..8629453008d 100644 --- a/templates/build.js +++ b/templates/build.js @@ -12,7 +12,8 @@ const { hideBin } = require('yargs/helpers') const argv = yargs(hideBin(process.argv)).argv const watch = argv.watch -const project = '../samples/seed' +const project = argv.project || '../samples/seed' + const loader = { '.eot': 'file', '.svg': 'file', diff --git a/templates/modern/layout/_master.tmpl b/templates/modern/layout/_master.tmpl index 888e8a93764..df8d2a9cd4a 100644 --- a/templates/modern/layout/_master.tmpl +++ b/templates/modern/layout/_master.tmpl @@ -24,6 +24,7 @@ {{#_noindex}}{{/_noindex}} {{#_enableSearch}}{{/_enableSearch}} {{#_enableNewTab}}{{/_enableNewTab}} + {{#docurl}}{{/docurl}} {{/redirect_url}} diff --git a/templates/modern/src/docfx.scss b/templates/modern/src/docfx.scss index b271714088e..a15b60b392d 100644 --- a/templates/modern/src/docfx.scss +++ b/templates/modern/src/docfx.scss @@ -3,6 +3,7 @@ * Licensed under the MIT License. See License.txt in the project root for license information. */ +$enable-grid-classes: false; $enable-important-utilities: false; $container-max-widths: ( diff --git a/templates/modern/src/docfx.ts b/templates/modern/src/docfx.ts index 4261a6c0151..7d04024ca26 100644 --- a/templates/modern/src/docfx.ts +++ b/templates/modern/src/docfx.ts @@ -7,8 +7,7 @@ import { breakText } from './helper' import { renderMarkdown } from './markdown' import { enableSearch } from './search' import { renderToc } from './toc' -import { renderBreadcrumb, renderInThisArticle, renderNavbar } from './nav' -import { renderThemePicker } from './theme' +import { renderBreadcrumb, renderFooter, renderInThisArticle, renderNavbar } from './nav' import 'bootstrap-icons/font/bootstrap-icons.scss' import './docfx.scss' @@ -30,7 +29,7 @@ document.addEventListener('DOMContentLoaded', function() { enableSearch() renderMarkdown() - renderThemePicker() + renderFooter() Promise.all([renderNavbar(), renderToc()]) .then(([navbar, toc]) => renderBreadcrumb([...navbar, ...toc])) diff --git a/templates/modern/src/layout.scss b/templates/modern/src/layout.scss index 42159d6fe5e..e5833d21857 100644 --- a/templates/modern/src/layout.scss +++ b/templates/modern/src/layout.scss @@ -9,20 +9,25 @@ $main-padding-top: 1rem; $main-padding-bottom: 4rem; // Makes a div sticky to top -@mixin sticky-top($top: 0) { - position: sticky; - top: $top; - - @if $top == 0 { +@mixin sticky-top { + @include media-breakpoint-up(md) { + position: sticky; + top: 0; z-index: 1030; - } @else { - z-index: 1020; + } +} + +@mixin stick-to-header { + @include media-breakpoint-up(md) { + position: sticky; + top: calc($header-height + $main-padding-top); } } html { width: 100vw; min-height: 100vh; + overflow-x: hidden; } body, @@ -36,9 +41,9 @@ body[data-layout="landing"] { display: flex; align-items: stretch; - @include media-breakpoint-up(md) { - @include sticky-top; + @include sticky-top; + @include media-breakpoint-up(md) { height: $header-height; } @@ -107,37 +112,27 @@ body[data-layout="landing"] { &[data-layout=""], &[data-layout="conceptual"] { >main { - display: grid; - gap: 3rem; - grid-template-columns: .4fr 1fr min-content; padding-bottom: 0; - @include media-breakpoint-down(lg) { - gap: 1rem; - } - - @include media-breakpoint-down(md) { - gap: 0; - grid-template-columns: 1fr; - grid-template-rows: 0 1fr; - } - >.toc-offcanvas { + flex: .35; display: block; overflow-x: hidden; overflow-y: auto; + max-width: 360px; max-height: calc(100vh - #{$header-height}); - @include sticky-top($header-height); + @include stick-to-header; @include media-breakpoint-down(md) { - width: 0; - height: 0; + flex: 0; } } >.content { + flex: 1; min-width: 0; + margin: 0 3rem; padding-bottom: $main-padding-bottom; >.actionbar { @@ -149,6 +144,14 @@ body[data-layout="landing"] { >.contribution { display: flex; } + + @include media-breakpoint-down(lg) { + margin: 0 1rem; + } + + @include media-breakpoint-down(md) { + margin: 0; + } } >.affix { @@ -158,7 +161,7 @@ body[data-layout="landing"] { overflow-x: hidden; overflow-y: auto; - @include sticky-top($header-height); + @include stick-to-header; @include media-breakpoint-down(xl) { display: none; diff --git a/templates/modern/src/nav.ts b/templates/modern/src/nav.ts index 65ad0489520..b9e722068cf 100644 --- a/templates/modern/src/nav.ts +++ b/templates/modern/src/nav.ts @@ -3,6 +3,7 @@ import { render, html } from 'lit-html' import { meta } from './helper' +import { themePicker } from './theme' import { TocNode } from './toc' export type NavItem = { @@ -44,6 +45,28 @@ export async function renderNavbar(): Promise { return activeItem ? [activeItem] : [] } +export function renderFooter() { + const footer = document.querySelector('footer>div') as HTMLElement + if (footer) { + render(html`${githubLink()} ${themePicker(renderFooter)}`, footer) + } + + function githubLink() { + const docurl = meta('docfx:docurl') + const github = parseGitHubRepo(docurl) + if (github) { + return html`` + } + } + + function parseGitHubRepo(url: string): string { + const match = /^https:\/\/github.com\/([^/]+\/[^/]+)/gi.exec(url) + if (match) { + return match[0] + } + } +} + export function renderBreadcrumb(breadcrumb: (NavItem | TocNode)[]) { const container = document.getElementById('breadcrumb') if (container) { diff --git a/templates/modern/src/theme.ts b/templates/modern/src/theme.ts index 24b00d07499..6b07ce8200c 100644 --- a/templates/modern/src/theme.ts +++ b/templates/modern/src/theme.ts @@ -1,11 +1,12 @@ // Copyright (c) Microsoft. All rights reserved. // Licensed under the MIT license. See LICENSE file in the project root for full license information. -import { html, render } from 'lit-html' +import { html } from 'lit-html' -setTheme(localStorage.getItem('theme') || 'auto') +type Theme = 'light' | 'dark' | 'auto' -function setTheme(theme) { +function setTheme(theme: Theme) { + localStorage.setItem('theme', theme) if (theme === 'auto') { document.body.setAttribute('data-bs-theme', window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') } else { @@ -13,29 +14,27 @@ function setTheme(theme) { } } -export function renderThemePicker() { - const footer = document.querySelector('footer>div') as HTMLElement - - renderCore(localStorage.getItem('theme') || 'auto') - - function renderCore(theme) { +export function themePicker(refresh: () => void) { + const theme = localStorage.getItem('theme') as Theme || 'auto' + setTheme(theme) + + const icon = theme === 'light' ? 'sun' : theme === 'dark' ? 'moon' : 'circle-half' + + return html` +
+ + +
` + + function changeTheme(e, theme: Theme) { + e.preventDefault() setTheme(theme) - - if (footer) { - const icon = theme === 'light' ? 'sun' : theme === 'dark' ? 'moon' : 'circle-half' - const themePicker = html` -
- - -
` - - render(themePicker, footer) - } + refresh() } } diff --git a/templates/modern/src/toc.ts b/templates/modern/src/toc.ts index dc42eed9fe6..acb20e3e9fd 100644 --- a/templates/modern/src/toc.ts +++ b/templates/modern/src/toc.ts @@ -45,7 +45,7 @@ export async function renderToc(): Promise { if (node.href) { const url = new URL(node.href, tocUrl) node.href = url.href - active = url.pathname === window.location.pathname + active = normalizeUrlPath(url) === normalizeUrlPath(window.location) } if (node.items) { @@ -89,4 +89,8 @@ export async function renderToc(): Promise { } })}` } + + function normalizeUrlPath(url: { pathname: string }): string { + return url.pathname.replace(/\/index\.html$/gi, '/') + } }