From f13df19b874e56ae3a2c5c95a1660d98e4111c98 Mon Sep 17 00:00:00 2001 From: polarathene <5098581+polarathene@users.noreply.github.com> Date: Thu, 11 Mar 2021 16:49:43 +1300 Subject: [PATCH] docs(styles): Add external link icon workaround Adds some third-party CSS as`mkdocs-material` doesn't seem interested in a PR to upstream this feature to the community. --- Uses a font icon approach for the external link as alternatives like SVG was reported in PR as breaking on Chrome. The logo has been made larger than theme default, it needs a little push from the left to align well with the tabs below it. --- Unrelated: Additionally experiment with the Instant Navigation feature. --- docs(styles): Various improvements Multiple related commits from original PR have been squashed into this. Some messages may be redundant due to loss of history. --- docs(styles): Minor improvements - Use relative path for external-link - UI enhancement for version selector - Improve inline documentation for `customizations.css` Make separate styling sections more evident (since we're not using multiple files or build tools). --- docs(styles): Replace permalink to fix UX bug --- docs(styles): Replace permalink feature for alternative approach Previous commit already switched `permalink` for `anchorlink` option, but the `#` symbol had UI concerns regarding font-size/scale and fitting into the gutter. Gutter change reverted, switch to REM units and symbol replaced by thin vertical rectangle scaled by font height, far better consistency for placement. --- docs(styles): Refactor the heading link style Effectively ended up making a border-left line style, just not as consistent and more complicated. Fixed that by adjusting styles. Adds optional background fill and restores inline code style for headings. --- docs/content/assets/css/customizations.css | 84 +++++++++++++++++++ docs/content/assets/fonts/external-link.woff | Bin 0 -> 1008 bytes docs/mkdocs.yml | 6 +- 3 files changed, 89 insertions(+), 1 deletion(-) create mode 100644 docs/content/assets/css/customizations.css create mode 100644 docs/content/assets/fonts/external-link.woff diff --git a/docs/content/assets/css/customizations.css b/docs/content/assets/css/customizations.css new file mode 100644 index 00000000..53fee32d --- /dev/null +++ b/docs/content/assets/css/customizations.css @@ -0,0 +1,84 @@ +/* This file adds our styling additions / fixes to maintain. */ + +/* ============================================================================================================= */ + +/* External Link icon feature. Rejected from upstreaming to `mkdocs-material`. +Alternative solution using SVG icon here (Broken on Chrome?): https://github.com/squidfunk/mkdocs-material/issues/2318#issuecomment-789461149 +Tab or Nav sidebar with non-relative links will prepend an icon (font glyph) +If you want to append instead, switch `::before` to `::after`. +*/ +/* reference the icon font to use */ +@font-face { + font-family: 'external-link'; + src: url('../fonts/external-link.woff') format('woff'); +} + +/* Matches the two nav link classes that start with `http` `href` values, regular docs pages use relative URLs instead. */ +.md-tabs__link[href^="http"]::before, .md-nav__link[href^="http"]::before { + display: inline-block; /* treat similar to text */ + font-family: 'external-link'; + content:'\0041'; /* represents "A" which our font renders as an icon instead of the "A" glyph */ + font-size: 80%; /* icon is a little too big by default, scale it down */ +} + +/* ============================================================================================================= */ + +/* UI Improvement: Header bar (top of page) adjustments - Increase scale of logo and adjust white-space */ +/* Make the logo larger without impacting other header components */ +.md-header__button.md-logo > img { transform: scale(180%); margin-left: 0.4rem; } +/* Reduce the white-space between the Logo and Title components */ +.md-header__title { margin-left: 0.3rem; } + +/* ============================================================================================================= */ + +/* UI Improvement: Add light colour bg for the version selector, with some rounded corners */ +.md-version__current { + background-color: rgb(255,255,255,0.18); /* white with 18% opacity */ + padding: 5px; + border-radius: 3px; +} + +/* ============================================================================================================= */ + +/* + UX Bugfix for permalink affecting typography in headings. + Upstream will not fix: https://github.com/squidfunk/mkdocs-material/issues/2369 +*/ + +/* Headings are configured to be links (instead of only the permalink symbol), removes the link colour */ +div.md-content article.md-content__inner a.toclink { + color: currentColor; +} + +/* Instead of a permalink symbol at the end of heading text, use a border line on the left spanning height of heading */ +/* Includes optional background fill with rounded right-side corners, and restores inline code style */ +/* NOTE: Headings with markdown links embedded disrupt the bg fill style, as they're not children of `a.toclink` element */ +div.md-content article.md-content__inner a.toclink { + display: inline-block; /* Enables multi-line support for both border and bg color */ + border-left: .2rem solid transparent; /* transparent placeholder to avoid heading shift during reveal transition */ + margin-left: -0.6rem; /* Offset heading to the left */ + padding-left: 0.4rem; /* Push heading back to original position, margin-left - border-left widths */ + transition: background-color 200ms,border-left 200ms; + + /* Only relevant if using background highlight style */ + border-radius: 0 0.25rem 0.25rem 0; + padding-right: 0.4rem; +} + +div.md-content article.md-content__inner a.toclink:hover, +div.md-content article.md-content__inner :target > a.toclink { + border-left: .2rem solid #448aff; /* highlight line on the left */ + background-color: #b3dbff6e; /* background highlight fill */ + transition: background-color 200ms,border-left 200ms; +} + +/* Upstream overrides some of the `code` element styles for headings, restore them */ +div.md-content article.md-content__inner a.toclink code { + padding: 0 0.3em; /* padding to the left and right, not top and bottom */ + border-radius: 0.2rem; /* 0.1rem of original style bit too small */ + background-color: var(--md-code-bg-color); +} + +.highlight.no-copy .md-clipboard { display: none; } + +/* ============================================================================================================= */ diff --git a/docs/content/assets/fonts/external-link.woff b/docs/content/assets/fonts/external-link.woff new file mode 100644 index 0000000000000000000000000000000000000000..6e888e08eb8c9d68a544cb12a2a6a303ad4783cb GIT binary patch literal 1008 zcmXT-cXMN4WB>x@4-8x&nk@&y2eDCsf3Ut0P~-~`+W~P{*w$p@iE&7HoVeGWu_LPA+1V@RsCEZ( zH91JM{J(kRUS08I(~X-<15|h>7Q}1S+|Djx>3?w1$}7K=b7^l{LR(|L$ArnxeJo=; zC(NJl+xkVo_Pe~(AFYr)UCk~Xj=u^DtXHga=FO8jg7$-}_6 zm=PG;6?1C)z5Nawh`6r*?YyOlk%Mh+f}sP`l`qN%7X&X!V+&%RYv2{V+}^xTXnU6V z0l5eU?L^rPjAjQ_zp8lTu1TL?Ui0+{gT-NUma_Y-*~gjG-;~815L_oK{xV;7`icI& z(<>gHENuOEvrzPVMQO}o%X=1%Q~GY+eRy}HgY5i1Zi}PSA1nRse=PKB(VHDT-i1$h zIQ@UHqpPu^Fy?UYj}M_sCLLI{Q6_Kc`t2XDta8cS;o6w@B67=%)hE5!E2n3(X?dor zP0C$A_4Ce)FRLzXG@Fu`G;LG5(&{Z{Mt)~vde@k5HG5|^d*SDMCv+Y VJ+?Ot8s|BJm>C$aF$e)80|54Ca)