Merge branch 'refactor/rxjs-typescript' into feature/landing-page

docs/getting-started.md

@@ -719,11 +719,13 @@ including more information regarding installation and usage:
 * [Search][32] (enabled by default)
 * [Minification][33]
 * [Revision date][34]
+* [Awesome pages][35]
 
 For further reference, the MkDocs wiki contains a list of all
-[available plugins][35].
+[available plugins][36].
 
   [32]: plugins/search.md
   [33]: plugins/minification.md
   [34]: plugins/revision-date.md
-  [35]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
+  [35]: plugins/awesome-pages.md
+  [36]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins

docs/plugins/search.md

@@ -9,9 +9,19 @@ and is implemented using [lunr.js][2] which includes stemmers for the English
 language by default, while stemmers for other languages are included with 
 [lunr-languages][3], both of which are integrated with this theme.
 
+!!! tip "Add the [localsearch][4] plugin to support search from `file://`"
+
+    While search will not work for the `file://` protocol, as web workers and
+    the use of `XMLHTTPRequest` are both blocked by modern browsers for security
+    reasons, the [localsearch][4] plugin and @squidfunk's [iframe-worker][5]
+    polyfill add support for cases where this is a mandatory requirement, e.g.,
+    for offline use.
+
   [1]: https://www.mkdocs.org/user-guide/configuration/#search
   [2]: https://lunrjs.com
   [3]: https://github.com/MihaiValentin/lunr-languages
+  [4]: https://github.com/wilhelmer/mkdocs-localsearch
+  [5]: https://github.com/squidfunk/iframe-worker
 
 ## Installation
 
@@ -102,7 +112,7 @@ plugins:
 
 > Default: `false`
 
-MkDocs can generate a [prebuilt index][4] of all pages during build time, which
+MkDocs can generate a [prebuilt index][6] of all pages during build time, which
 provides performance improvements at the cost of more bandwidth. This may be
 beneficial for large documentation projects that are served with appropriate
 HTTP headers (e.g. `Content-Encoding: gzip`).
@@ -116,7 +126,7 @@ plugins:
       prebuild_index: true
 ```
 
-  [4]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
+  [6]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
 
 ## Usage
 

material/assets/manifest.json

@@ -1,6 +1,6 @@
 {
-  "assets/javascripts/bundle.js": "assets/javascripts/bundle.0ddca959.min.js",
-  "assets/javascripts/bundle.js.map": "assets/javascripts/bundle.0ddca959.min.js.map",
+  "assets/javascripts/bundle.js": "assets/javascripts/bundle.ed8df680.min.js",
+  "assets/javascripts/bundle.js.map": "assets/javascripts/bundle.ed8df680.min.js.map",
   "assets/javascripts/vendor.js": "assets/javascripts/vendor.c1fcc1cc.min.js",
   "assets/javascripts/vendor.js.map": "assets/javascripts/vendor.c1fcc1cc.min.js.map",
   "assets/javascripts/worker/search.js": "assets/javascripts/worker/search.3bc815f0.min.js",

material/base.html

@@ -29,7 +29,7 @@
         <meta name="author" content="{{ config.site_author }}">
       {% endif %}
       <link rel="shortcut icon" href="{{ config.theme.favicon | url }}">
-      <meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-material-5.0.0rc3">
+      <meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-material-5.0.0rc4">
     {% endblock %}
     {% block htmltitle %}
       {% if page and page.meta and page.meta.title %}
@@ -179,7 +179,7 @@
     </div>
     {% block scripts %}
       <script src="{{ 'assets/javascripts/vendor.c1fcc1cc.min.js' | url }}"></script>
-      <script src="{{ 'assets/javascripts/bundle.0ddca959.min.js' | url }}"></script>
+      <script src="{{ 'assets/javascripts/bundle.ed8df680.min.js' | url }}"></script>
       {%- set translations = {} -%}
       {%- for key in [
         "clipboard.copy",

material/overrides/main.html

@@ -7,7 +7,7 @@
   {% if page and page.title and not page.is_homepage %}
     {% set title = config.site_name ~ " - " ~ page.title | striptags %}
   {% endif %}
-  {% set image = 'assets/images/illustration.png' | url %}
+  {% set image = config.site_url ~ 'assets/images/illustration.png' %}
   <meta property="og:title" content="{{ title }}">
   <meta property="og:description" content="{{ config.site_description }}">
   <meta property="og:url" content="{{ page.canonical_url }}">
@@ -20,5 +20,5 @@
   <meta name="twitter:image" content="{{ image }}">
 {% endblock %}
 {% block announce %}
-  Material for MkDocs 5.0.0rc3
+  Material for MkDocs 5.0.0rc4
 {% endblock %}

mkdocs.yml

@@ -20,12 +20,12 @@
 
 # Project information
 site_name: Material for MkDocs
+site_url: https://squidfunk.github.io/mkdocs-material/
+site_author: Martin Donath
 site_description: >-
   Create a branded static site from a set of Markdown files to host the
   documentation of your Open Source or commercial project – customizable,
   searchable, mobile-friendly, 40+ languages
-site_author: Martin Donath
-site_url: https://squidfunk.github.io/mkdocs-material/
 
 # Repository
 repo_name: squidfunk/mkdocs-material
@@ -52,7 +52,7 @@ theme:
   language: en
   features:
     - tabs
-    - instant
+    #- instant
   palette:
     primary: indigo
     accent: indigo

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "mkdocs-material",
-  "version": "5.0.0rc3",
+  "version": "5.0.0rc4",
   "lockfileVersion": 1,
   "requires": true,
   "dependencies": {
@@ -1828,8 +1828,7 @@
         },
         "kind-of": {
           "version": "6.0.2",
-          "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.2.tgz",
-          "integrity": "sha512-s5kLOcnH0XqDO+FvuaLX8DDjZ18CGFk7VygH40QoKPUQhW4e2rvM0rwUq0t8IQDOwYSeLK01U90OjzBTme2QqA==",
+          "resolved": "",
           "dev": true
         }
       }
@@ -2810,8 +2809,7 @@
         },
         "minimist": {
           "version": "1.2.0",
-          "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.0.tgz",
-          "integrity": "sha1-o1AIsg9BOD7sH7kU9M1d95omQoQ=",
+          "resolved": "",
           "dev": true
         },
         "normalize-path": {
@@ -3415,8 +3413,7 @@
         },
         "kind-of": {
           "version": "6.0.2",
-          "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.2.tgz",
-          "integrity": "sha512-s5kLOcnH0XqDO+FvuaLX8DDjZ18CGFk7VygH40QoKPUQhW4e2rvM0rwUq0t8IQDOwYSeLK01U90OjzBTme2QqA==",
+          "resolved": "",
           "dev": true
         }
       }
@@ -7773,8 +7770,7 @@
         },
         "kind-of": {
           "version": "6.0.2",
-          "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.2.tgz",
-          "integrity": "sha512-s5kLOcnH0XqDO+FvuaLX8DDjZ18CGFk7VygH40QoKPUQhW4e2rvM0rwUq0t8IQDOwYSeLK01U90OjzBTme2QqA==",
+          "resolved": "",
           "dev": true
         }
       }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mkdocs-material",
-  "version": "5.0.0rc3",
+  "version": "5.0.0rc4",
   "description": "A Material Design theme for MkDocs",
   "keywords": [
     "mkdocs",

src/assets/javascripts/browser/element/_/index.ts

@@ -90,6 +90,21 @@ export function getElements<T extends HTMLElement>(
 
 /* ------------------------------------------------------------------------- */
 
+/**
+ * Create an element
+ *
+ * @template T - Tag name type
+ *
+ * @param tagName - Tag name
+ *
+ * @return Element
+ */
+export function createElement<
+  T extends keyof HTMLElementTagNameMap
+>(tagName: T): HTMLElementTagNameMap[T] {
+  return document.createElement(tagName)
+}
+
 /**
  * Replace an element with another element
  *

src/assets/javascripts/browser/location/hash/index.ts

@@ -23,6 +23,8 @@
 import { Observable, fromEvent } from "rxjs"
 import { filter, map, share, startWith } from "rxjs/operators"
 
+import { createElement } from "browser"
+
 /* ----------------------------------------------------------------------------
  * Functions
  * ------------------------------------------------------------------------- */
@@ -47,7 +49,7 @@ export function getLocationHash(): string {
  * @param hash - Location hash
  */
 export function setLocationHash(hash: string): void {
-  const el = document.createElement("a")
+  const el = createElement("a")
   el.href = hash
   el.addEventListener("click", ev => ev.stopPropagation())
   el.click()

src/assets/javascripts/components/hero/_/index.ts

@@ -21,7 +21,11 @@
  */
 
 import { Observable, OperatorFunction, pipe } from "rxjs"
-import { distinctUntilChanged, map, switchMap } from "rxjs/operators"
+import {
+  distinctUntilKeyChanged,
+  map,
+  switchMap
+} from "rxjs/operators"
 
 import { Viewport, watchViewportAt } from "browser"
 
@@ -69,7 +73,7 @@ export function mountHero(
     switchMap(el => watchViewportAt(el, { header$, viewport$ })
       .pipe(
         map(({ offset: { y } }) => ({ hidden: y >= 20 })),
-        distinctUntilChanged(),
+        distinctUntilKeyChanged("hidden"),
         applyHero(el)
       )
     )

src/assets/javascripts/components/main/react/index.ts

@@ -88,8 +88,8 @@ export function watchMain(
       shareReplay(1)
     )
 
-  /* Compute the main area's top and bottom markers */
-  const marker$ = adjust$
+  /* Compute the main area's top and bottom borders */
+  const border$ = adjust$
     .pipe(
       switchMap(() => watchElementSize(el)
         .pipe(
@@ -104,7 +104,7 @@ export function watchMain(
     )
 
   /* Compute the main area's offset, visible height and if we scrolled past */
-  return combineLatest([adjust$, marker$, viewport$])
+  return combineLatest([adjust$, border$, viewport$])
     .pipe(
       map(([header, { top, bottom }, { offset: { y }, size: { height } }]) => {
         height = Math.max(0, height
@@ -114,7 +114,7 @@ export function watchMain(
         return {
           offset: top - header,
           height,
-          active: y >= top - header
+          active: top - header <= y
         }
       }),
       distinctUntilChanged<Main>((a, b) => {

src/assets/javascripts/components/tabs/_/index.ts

@@ -21,7 +21,11 @@
  */
 
 import { Observable, OperatorFunction, of, pipe } from "rxjs"
-import { distinctUntilChanged, map, switchMap } from "rxjs/operators"
+import {
+  distinctUntilKeyChanged,
+  map,
+  switchMap
+} from "rxjs/operators"
 
 import { Viewport, watchViewportAt } from "browser"
 
@@ -76,7 +80,7 @@ export function mountTabs(
             return watchViewportAt(el, { header$, viewport$ })
               .pipe(
                 map(({ offset: { y } }) => ({ hidden: y >= 10 })),
-                distinctUntilChanged(),
+                distinctUntilKeyChanged("hidden"),
                 applyTabs(el)
               )
 

src/assets/javascripts/components/toc/anchor/react/index.ts

@@ -41,7 +41,7 @@ import {
   tap
 } from "rxjs/operators"
 
-import { Viewport, getElement } from "browser"
+import { Viewport, getElement, watchElementSize } from "browser"
 
 import { Header } from "../../../header"
 import { AnchorList } from "../_"
@@ -106,9 +106,9 @@ export function watchAnchorList(
     )
 
   /* Compute partition of previous and next anchors */
-  const partition$ = viewport$
+  const partition$ = watchElementSize(document.body)
     .pipe(
-      distinctUntilKeyChanged("size"),
+      distinctUntilKeyChanged("height"),
 
       /* Build index to map anchor paths to vertical offsets */
       map(() => {

src/assets/javascripts/integrations/dialog/index.ts

@@ -29,6 +29,8 @@ import {
   tap
 } from "rxjs/operators"
 
+import { createElement } from "browser"
+
 /* ----------------------------------------------------------------------------
  * Types
  * ------------------------------------------------------------------------- */
@@ -57,7 +59,7 @@ export function setupDialog(
   const dialog$ = new Subject<string>()
 
   /* Create dialog */
-  const dialog = document.createElement("div")                                  // TODO: improve scoping
+  const dialog = createElement("div")                                           // TODO: improve scoping
   dialog.classList.add("md-dialog", "md-typeset")
 
   /* Display dialog */

src/assets/javascripts/patches/script/index.ts

@@ -23,7 +23,11 @@
 import { Observable } from "rxjs"
 import { map, skip, withLatestFrom } from "rxjs/operators"
 
-import { getElements } from "browser"
+import {
+  createElement,
+  getElements,
+  replaceElement
+} from "browser"
 import { useComponent } from "components"
 
 /* ----------------------------------------------------------------------------
@@ -63,10 +67,10 @@ export function patchScripts(
   els$.subscribe(els => {
     for (const el of els) {
       if (el.src || /(^|\/javascript)$/i.test(el.type)) {
-        const script = document.createElement("script")
+        const script = createElement("script")
         const key = el.src ? "src" : "textContent"
         script[key] = el[key]!
-        el.replaceWith(script)
+        replaceElement(el, script)
       }
     }
   })

src/assets/javascripts/patches/table/index.ts

@@ -23,7 +23,11 @@
 import { Observable } from "rxjs"
 import { map } from "rxjs/operators"
 
-import { getElements } from "browser"
+import {
+  createElement,
+  getElements,
+  replaceElement
+} from "browser"
 import { renderTable } from "templates"
 
 /* ----------------------------------------------------------------------------
@@ -52,15 +56,15 @@ interface MountOptions {
 export function patchTables(
   { document$ }: MountOptions
 ): void {
-  const sentinel = document.createElement("table")
+  const sentinel = createElement("table")
   document$
     .pipe(
       map(() => getElements<HTMLTableElement>("table:not([class])"))
     )
       .subscribe(els => {
         for (const el of els) {
-          el.replaceWith(sentinel)
-          sentinel.replaceWith(renderTable(el))
+          replaceElement(el, sentinel)
+          replaceElement(sentinel, renderTable(el))
         }
       })
 }

src/assets/javascripts/utilities/jsx/index.ts

@@ -54,21 +54,21 @@ type Child =
 /**
  * Create an element
  *
- * @param tag - HTML or SVG tag
+ * @param tagName - HTML or SVG tag
  *
  * @return Element
  */
-function createElement(tag: string): HTMLElement | SVGElement {
-  switch (tag) {
+function createElement(tagName: string): HTMLElement | SVGElement {
+  switch (tagName) {
 
     /* SVG elements */
     case "svg":
     case "path":
-      return document.createElementNS("http://www.w3.org/2000/svg", tag)
+      return document.createElementNS("http://www.w3.org/2000/svg", tagName)
 
     /* HTML elements */
     default:
-      return document.createElement(tag)
+      return document.createElement(tagName)
   }
 }
 
@@ -137,16 +137,16 @@ function appendChild(
 /**
  * JSX factory
  *
- * @param tag - HTML or SVG tag
+ * @param tagName - HTML or SVG tag
  * @param attributes - HTML attributes
  * @param children - Child elements
  *
  * @return Element
  */
 export function h(
-  tag: string, attributes: Attributes | null, ...children: Child[]
+  tagName: string, attributes: Attributes | null, ...children: Child[]
 ): HTMLElement | SVGElement {
-  const el = createElement(tag)
+  const el = createElement(tagName)
 
   /* Set attributes, if any */
   if (attributes)

src/overrides/main.html

@@ -22,7 +22,6 @@
 
 {% extends "base.html" %}
 
-
 <!-- Custom front matter -->
 {% block extrahead %}
 
@@ -32,8 +31,8 @@
     {% set title = config.site_name ~ " - " ~ page.title | striptags %}
   {% endif %}
 
-  <!-- Determine image -->
-  {% set image = 'assets/images/illustration.png' | url %}
+  <!-- The image needs to have an absolute URL -->
+  {% set image = config.site_url ~ 'assets/images/illustration.png' %}
 
   <!-- Open graph meta tags -->
   <meta property="og:title" content="{{ title }}" />
@@ -52,5 +51,5 @@
 
 <!-- Announcement bar -->
 {% block announce %}
-  Material for MkDocs 5.0.0rc3
+  Material for MkDocs 5.0.0rc4
 {% endblock %}