Cool_Tools/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-30 18:24:35 +01:00
Code Issues Releases Wiki Activity

Merge pull request #6662 from squidfunk/fix/instant-loading-bugs

Browse Source 
Fixed instant navigation bugs
This commit is contained in:
Martin Donath 2024-01-24 10:48:18 +07:00 committed by GitHub
commit 943e97801e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
12 changed files with 442 additions and 394 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
material/overrides/assets/javascripts/custom.526c59dc.min.js → material/overrides/assets/javascripts/custom.129bd6ad.min.js vendored
View File

File diff suppressed because one or more lines are too long

6
material/overrides/assets/javascripts/custom.526c59dc.min.js.map → material/overrides/assets/javascripts/custom.129bd6ad.min.js.map
View File

File diff suppressed because one or more lines are too long

2
material/overrides/main.html
View File

@ -23,5 +23,5 @@
{% endblock %}
{% block scripts %}
{{ super() }}
<script src="{{ 'assets/javascripts/custom.526c59dc.min.js' | url }}"></script>
<script src="{{ 'assets/javascripts/custom.129bd6ad.min.js' | url }}"></script>
{% endblock %}

29
material/templates/assets/javascripts/bundle.a963951d.min.js vendored
View File

File diff suppressed because one or more lines are too long

29
material/templates/assets/javascripts/bundle.c18c5fb9.min.js vendored Normal file
View File

File diff suppressed because one or more lines are too long

8
material/templates/assets/javascripts/bundle.a963951d.min.js.map → material/templates/assets/javascripts/bundle.c18c5fb9.min.js.map
View File

File diff suppressed because one or more lines are too long

2
material/templates/base.html
View File

@ -249,7 +249,7 @@
</script>
{% endblock %}
{% block scripts %}
<script src="{{ 'assets/javascripts/bundle.a963951d.min.js' | url }}"></script>
<script src="{{ 'assets/javascripts/bundle.c18c5fb9.min.js' | url }}"></script>
{% for script in config.extra_javascript %}
{{ script | script_tag }}
{% endfor %}

51
src/templates/assets/javascripts/browser/request/index.ts
View File

@ -46,13 +46,20 @@ interface Options {
/**
* Fetch the given URL
*
* If the request fails (e.g. when dispatched from `file://` locations), the
* observable will complete without emitting a value.
* This function returns an observable that emits the response as a blob and
* completes, or emits an error if the request failed. The caller can cancel
* the request by unsubscribing at any time, which will automatically abort
* the inflight request and complete the observable.
*
* Note that we use `XMLHTTPRequest` not because we're nostalgic, but because
* it's the only way to get progress events for downloads and also allow for
* cancellation of requests, as the official Fetch API does not support this
* yet, even though we're already in 2024.
*
* @param url - Request URL
* @param options - Options
*
* @returns Response observable
* @returns Data observable
*/
export function request(
url: URL | string, options?: Options
@ -67,6 +74,8 @@ export function request(
if (req.status >= 200 && req.status < 300) {
observer.next(req.response)
observer.complete()
// Every response that is not in the 2xx range is considered an error
} else {
observer.error(new Error(req.statusText))
}
@ -74,12 +83,12 @@ export function request(
// Handle network errors
req.addEventListener("error", () => {
observer.error(new Error("Network Error"))
observer.error(new Error("Network error"))
})
// Handle aborted requests
req.addEventListener("abort", () => {
observer.error(new Error("Request aborted"))
observer.complete()
})
// Handle download progress
@ -87,9 +96,12 @@ export function request(
req.addEventListener("progress", event => {
if (event.lengthComputable) {
options.progress$!.next((event.loaded / event.total) * 100)
} else { // https://bugs.chromium.org/p/chromium/issues/detail?id=463622
const totalFromHeader = Number(req.getResponseHeader("Content-Length")) || 0
options.progress$!.next((event.loaded / totalFromHeader) * 100)
// Hack: Chromium doesn't report the total number of bytes if content
// is compressed, so we need this fallback - see https://t.ly/ZXofI
} else {
const length = req.getResponseHeader("Content-Length") ?? 0
options.progress$!.next((event.loaded / +length) * 100)
}
})
@ -97,8 +109,9 @@ export function request(
options.progress$.next(5)
}
// Send request
// Send request and automatically abort request upon unsubscription
req.send()
return () => req.abort()
})
}
@ -125,6 +138,26 @@ export function requestJSON<T>(
)
}
/**
* Fetch HTML from the given URL
*
* @param url - Request URL
* @param options - Options
*
* @returns Data observable
*/
export function requestHTML(
url: URL | string, options?: Options
): Observable<Document> {
const dom = new DOMParser()
return request(url, options)
.pipe(
switchMap(res => res.text()),
map(res => dom.parseFromString(res, "text/html")),
shareReplay(1)
)
}
/**
* Fetch XML from the given URL
*

525
src/templates/assets/javascripts/integrations/instant/index.ts
View File

@ -24,23 +24,21 @@ import {
EMPTY,
Observable,
Subject,
bufferCount,
catchError,
combineLatestWith,
concat,
debounceTime,
distinctUntilChanged,
distinctUntilKeyChanged,
endWith,
filter,
fromEvent,
ignoreElements,
map,
merge,
of,
sample,
share,
skip,
startWith,
switchMap,
take,
tap,
withLatestFrom
} from "rxjs"
@ -50,13 +48,13 @@ import {
getElements,
getLocation,
getOptionalElement,
request,
requestHTML,
setLocation,
setLocationHash
} from "~/browser"
import { getComponentElement } from "~/components"
import { fetchSitemap } from "../sitemap"
import { Sitemap, fetchSitemap } from "../sitemap"
/* ----------------------------------------------------------------------------
* Helper types
@ -68,217 +66,109 @@ import { fetchSitemap } from "../sitemap"
interface SetupOptions {
location$: Subject<URL> // Location subject
viewport$: Observable<Viewport> // Viewport observable
progress$: Subject<number> // Progress suject
progress$: Subject<number> // Progress subject
}
/* ----------------------------------------------------------------------------
* Helper functions
* ------------------------------------------------------------------------- */
/**
* Handle clicks on internal URLs while skipping external URLs
*
* @param ev - Mouse event
* @param sitemap - Sitemap
*
* @returns URL observable
*/
function handle(
ev: MouseEvent, sitemap: Sitemap
): Observable<URL> {
if (!(ev.target instanceof Element))
return EMPTY
// Skip, as target is not within a link - clicks on non-link elements are
// also captured, which we need to exclude from processing
const el = ev.target.closest("a")
if (el === null)
return EMPTY
// Skip, as link opens in new window - we now know we have captured a click
// on a link, but the link either has a `target` property defined, or the
// user pressed the `meta` or `ctrl` key to open it in a new window. Thus,
// we need to filter this event as well.
if (el.target || ev.metaKey || ev.ctrlKey)
return EMPTY
// Next, we must check if the URL is relevant for us, i.e., if it's an
// internal link to a page that is managed by MkDocs. Only then we can be
// sure that the structure of the page to be loaded adheres to the current
// document structure and can subsequently be injected into it without doing
// a full reload. For this reason, we must canonicalize the URL by removing
// all search parameters and hash fragments.
const url = new URL(el.href)
url.search = url.hash = ""
// Skip, if URL is not included in the sitemap - this could be the case when
// linking between versions or languages, or to another page that the author
// included as part of the build, but that is not managed by MkDocs. In that
// case we must not continue with instant navigation.
if (!sitemap.has(`${url}`))
return EMPTY
// We now know that we have a link to an internal page, so we prevent the
// browser from navigation and emit the URL for instant navigation. Note that
// this also includes anchor links, which means we need to implement anchor
// positioning ourselves. The reason for this is that if we wouldn't manage
// anchor links as well, scroll restoration will not work correctly (e.g.
// following an anchor link and scrolling).
ev.preventDefault()
return of(new URL(el.href))
}
/**
* Create a map of head elements for lookup and replacement
*
* @param head - Document head
* @param document - Document
*
* @returns Element map
* @returns Tag map
*/
function lookup(head: HTMLHeadElement): Map<string, HTMLElement> {
// @todo When resolving URLs, we must make sure to use the correct base for
// resolution. The next time we refactor instant loading, we should use the
// location subject as a source, which is also used for anchor links tracking,
// but for now we just rely on canonical.
const canonical = getOptionalElement<HTMLLinkElement>("[rel=canonical]", head)
if (typeof canonical !== "undefined")
canonical.href = canonical.href.replace("//localhost:", "//127.0.0.1:")
// Create tag map and index elements in head
function head(document: Document): Map<string, HTMLElement> {
const tags = new Map<string, HTMLElement>()
for (const el of getElements(":scope > *", head)) {
let html = el.outerHTML
// If the current element is a style sheet or script, we must resolve the
// URL relative to the current location and make it absolute, so it's easy
// to deduplicate it later on by comparing the outer HTML of tags. We must
// keep identical style sheets and scripts without replacing them.
for (const key of ["href", "src"]) {
const value = el.getAttribute(key)!
if (value === null)
continue
// Resolve URL relative to current location
const url = new URL(value, canonical?.href)
const ref = el.cloneNode() as HTMLElement
// Set resolved URL and retrieve HTML for deduplication
ref.setAttribute(key, `${url}`)
html = ref.outerHTML
break
}
// Index element in tag map
tags.set(html, el)
}
for (const el of getElements(":scope > *", document.head))
tags.set(el.outerHTML, el)
// Return tag map
return tags
}
/* ----------------------------------------------------------------------------
* Functions
* ------------------------------------------------------------------------- */
/**
* Set up instant navigation
* Resolve relative URLs in the given document
*
* This is a heavily orchestrated operation - see inline comments to learn how
* this works with Material for MkDocs, and how you can hook into it.
*
* @param options - Options
* @param document - Document
*
* @returns Document observable
*/
export function setupInstantNavigation(
{ location$, viewport$, progress$ }: SetupOptions
): Observable<Document> {
const config = configuration()
if (location.protocol === "file:")
return EMPTY
function resolve(document: Document): Observable<Document> {
for (const el of getElements<HTMLLinkElement>("[href], [src]", document))
for (const key in ["href", "src"]) {
const value = el.getAttribute(key)
if (!/^(?:[a-z]+:)?\/\//i.test(value!))
el.href = el.href
}
// Load sitemap immediately, so we have it available when the user initiates
// the first instant navigation request, and canonicalize URLs to the current
// base URL. The base URL will remain stable in between loads, as it's only
// read at the first initialization of the application.
const sitemap$ = fetchSitemap()
.pipe(
map(paths => paths.map(path => `${new URL(path, config.base)}`))
)
// Return document observable
return of(document)
}
// Intercept inter-site navigation - to keep the number of event listeners
// low we use the fact that uncaptured events bubble up to the body. This also
// has the nice property that we don't need to detach and then again attach
// event listeners when instant navigation occurs.
const instant$ = fromEvent<MouseEvent>(document.body, "click")
.pipe(
withLatestFrom(sitemap$),
switchMap(([ev, sitemap]) => {
if (!(ev.target instanceof Element))
return EMPTY
// Skip, as target is not within a link - clicks on non-link elements
// are also captured, which we need to exclude from processing
const el = ev.target.closest("a")
if (el === null)
return EMPTY
// Skip, as link opens in new window - we now know we have captured a
// click on a link, but the link either has a `target` property defined,
// or the user pressed the `meta` or `ctrl` key to open it in a new
// window. Thus, we need to filter those events, too.
if (el.target || ev.metaKey || ev.ctrlKey)
return EMPTY
// Next, we must check if the URL is relevant for us, i.e., if it's an
// internal link to a page that is managed by MkDocs. Only then we can
// be sure that the structure of the page to be loaded adheres to the
// current document structure and can subsequently be injected into it
// without doing a full reload. For this reason, we must canonicalize
// the URL by removing all search parameters and hash fragments.
const url = new URL(el.href)
url.search = url.hash = ""
// Skip, if URL is not included in the sitemap - this could be the case
// when linking between versions or languages, or to another page that
// the author included as part of the build, but that is not managed by
// MkDocs. In that case we must not continue with instant navigation.
if (!sitemap.includes(`${url}`))
return EMPTY
// We now know that we have a link to an internal page, so we prevent
// the browser from navigation and emit the URL for instant navigation.
// Note that this also includes anchor links, which means we need to
// implement anchor positioning ourselves. The reason for this is that
// if we wouldn't manage anchor links as well, scroll restoration will
// not work correctly (e.g. following an anchor link and scrolling).
ev.preventDefault()
return of(new URL(el.href))
}),
share()
)
// Before fetching for the first time, resolve the absolute favicon position,
// as the browser will try to fetch the icon immediately
instant$.pipe(take(1))
.subscribe(() => {
const favicon = getOptionalElement<HTMLLinkElement>("link[rel=icon]")
if (typeof favicon !== "undefined")
favicon.href = favicon.href
})
// Enable scroll restoration before window unloads - this is essential to
// ensure that full reloads (F5) restore the viewport offset correctly. If
// only popstate events wouldn't reset the scroll position prior to their
// emission, we could just reset this in popstate. Meh.
fromEvent(window, "beforeunload")
.subscribe(() => {
history.scrollRestoration = "auto"
})
// When an instant navigation event occurs, disable scroll restoration, since
// we must normalize and synchronize the behavior across all browsers. For
// instance, when the user clicks the back or forward button, the browser
// would immediately jump to the position of the previous document.
instant$.pipe(withLatestFrom(viewport$))
.subscribe(([url, { offset }]) => {
history.scrollRestoration = "manual"
// While it would be better UX to defer the history state change until the
// document was fully fetched and parsed, we must schedule it here, since
// popstate events are emitted when history state changes happen. Moreover
// we need to back up the current viewport offset, so we can restore it
// when popstate events occur, e.g., when the browser's back and forward
// buttons are used for navigation.
history.replaceState(offset, "")
history.pushState(null, "", url)
})
// Emit URL that should be fetched via instant navigation on location subject,
// which was passed into this function. Instant navigation can be intercepted
// by other parts of the application, which can synchronously back up or
// restore state before instant navigation happens.
instant$.subscribe(location$)
// Fetch document - when fetching, we could use `responseType: document`, but
// since all MkDocs links are relative, we need to make sure that the current
// location matches the document we just loaded. Otherwise any relative links
// in the document might use the old location. If the request fails for some
// reason, we fall back to regular navigation and set the location explicitly,
// which will force-load the page. Furthermore, we must pre-warm the buffer
// for the duplicate check, or the first click on an anchor link will also
// trigger an instant navigation event, which doesn't make sense.
const response$ = location$
.pipe(
startWith(getLocation()),
distinctUntilKeyChanged("pathname"),
skip(1),
switchMap(url => request(url, { progress$ })
.pipe(
catchError(() => {
setLocation(url, true)
return EMPTY
})
)
)
)
// Initialize the DOM parser, parse the returned HTML, and replace selected
// components before handing control down to the application
const dom = new DOMParser()
const document$ = response$
.pipe(
switchMap(res => res.text()),
switchMap(res => {
const next = dom.parseFromString(res, "text/html")
/**
* Create a map of head elements for lookup and replacement
*
* @param next - Next document
*
* @returns Document observable
*/
function inject(next: Document): Observable<Document> {
for (const selector of [
"[data-md-component=announce]",
"[data-md-component=container]",
@ -301,36 +191,15 @@ export function setupInstantNavigation(
}
// Update meta tags
const source = lookup(document.head)
const target = lookup(next.head)
for (const [html, el] of target) {
// Hack: skip stylesheets and scripts until we manage to replace them
// entirely in order to omit flashes of white content @todo refactor
if (
el.getAttribute("rel") === "stylesheet" ||
el.hasAttribute("src")
)
continue
if (source.has(html)) {
source.delete(html)
} else {
const tags = head(document)
for (const [html, el] of head(next))
if (tags.has(html))
tags.delete(html)
else
document.head.appendChild(el)
}
}
// Remove meta tags that are not present in the new document
for (const el of source.values())
// Hack: skip stylesheets and scripts until we manage to replace them
// entirely in order to omit flashes of white content @todo refactor
if (
el.getAttribute("rel") === "stylesheet" ||
el.hasAttribute("src")
)
continue
else
for (const el of tags.values())
el.remove()
// After components and meta tags were replaced, re-evaluate scripts
@ -360,29 +229,162 @@ export function setupInstantNavigation(
ignoreElements(),
endWith(next)
)
}),
}
/* ----------------------------------------------------------------------------
* Functions
* ------------------------------------------------------------------------- */
/**
* Set up instant navigation
*
* This is a heavily orchestrated operation - see inline comments to learn how
* this works with Material for MkDocs, and how you can hook into it.
*
* @param options - Options
*
* @returns Document observable
*/
export function setupInstantNavigation(
{ location$, viewport$, progress$ }: SetupOptions
): Observable<Document> {
const config = configuration()
if (location.protocol === "file:")
return EMPTY
// Load sitemap immediately, so we have it available when the user initiates
// the first navigation request, so there's no perceived delay.
const sitemap$ = fetchSitemap(config.base)
// Since we might be on a slow connection, the user might trigger multiple
// instant navigation events that overlap. MkDocs produces relative URLs for
// all internal links, which becomes a problem in this case, because we need
// to change the base URL the moment the user clicks a link that should be
// intercepted in order to be consistent with popstate, which means that the
// base URL would now be incorrect when resolving another relative link from
// the same site. For this reason we always resolve all relative links to
// absolute links, so we can be sure this never happens.
of(document)
.subscribe(resolve)
// --------------------------------------------------------------------------
// Navigation interception
// --------------------------------------------------------------------------
// Intercept navigation - to keep the number of event listeners down we use
// the fact that uncaptured events bubble up to the body. This has the nice
// property that we don't need to detach and then re-attach event listeners
// when the document is replaced after a navigation event.
const instant$ =
fromEvent<MouseEvent>(document.body, "click")
.pipe(
combineLatestWith(sitemap$),
switchMap(([ev, sitemap]) => handle(ev, sitemap)),
share()
)
// Intercept popstate events, e.g. when using the browser's back and forward
// buttons, and emit new location for fetching and parsing
const popstate$ = fromEvent<PopStateEvent>(window, "popstate")
popstate$.pipe(map(getLocation))
// Intercept history change events, e.g. when the user uses the browser's
// back or forward buttons, and emit new location for fetching and parsing
const history$ =
fromEvent<PopStateEvent>(window, "popstate")
.pipe(
map(getLocation),
share()
)
// While it would be better UX to defer navigation events until the document
// is fully fetched and parsed, we must schedule it here to synchronize with
// popstate events, as they are emitted immediately. Moreover we need to
// store the current viewport offset for scroll restoration later on.
instant$.pipe(withLatestFrom(viewport$))
.subscribe(([url, { offset }]) => {
history.replaceState(offset, "")
history.pushState(null, "", url)
})
// Emit URLs that should be fetched via instant navigation on location subject
// which was passed into this function. The state of instant navigation can be
// intercepted by other parts of the application, which can synchronously back
// up or restore state before or after instant navigation happens.
merge(instant$, history$)
.subscribe(location$)
// Intercept clicks on anchor links, and scroll document into position - as
// we disabled scroll restoration, we need to do this manually here
location$
// --------------------------------------------------------------------------
// Fetching and parsing
// --------------------------------------------------------------------------
// Fetch document - we deduplicate requests to the same location, so we don't
// end up with multiple requests for the same page. We use `switchMap`, since
// we want to cancel the previous request when a new one is triggered, which
// is automatically handled by the observable returned by `request`. This is
// essential to ensure a good user experience, as we don't want to load pages
// that are not needed anymore, e.g., when the user clicks multiple links in
// quick succession or on slow connections. If the request fails for some
// reason, we fall back and use regular navigation, forcing a reload.
const document$ = location$
.pipe(
startWith(getLocation()),
bufferCount(2, 1),
filter(([prev, next]) => (
prev.pathname === next.pathname &&
prev.hash !== next.hash
distinctUntilKeyChanged("pathname"),
switchMap(url => requestHTML(url, { progress$ })
.pipe(
catchError(() => {
setLocation(url, true)
return EMPTY
})
)
),
// The document was successfully fetched and parsed, so we can inject its
// contents into the currently active document
switchMap(resolve),
switchMap(inject),
share()
)
// --------------------------------------------------------------------------
// Scroll restoration
// --------------------------------------------------------------------------
// Handle scroll restoration - we must restore the viewport offset after the
// document has been fetched and injected, and every time the user clicks an
// anchor that leads to an element on the same page, which might also happen
// when the user uses the back or forward button.
merge(
document$.pipe(withLatestFrom(location$, (_, url) => url)),
// Handle instant navigation events that are triggered by the user clicking
// on an anchor link with a hash fragment different from the current one, as
// well as from popstate events, which are emitted when the user navigates
// back and forth between pages. We use a two-layered subscription to scope
// the scroll restoration to the current page, as we don't need to restore
// the viewport offset when the user navigates to a different page, as this
// is already handled by the previous observable.
location$.pipe(
distinctUntilKeyChanged("pathname"),
switchMap(() => location$),
distinctUntilKeyChanged("hash"),
),
// Handle instant navigation events that are triggered by the user clicking
// on an anchor link with the same hash fragment as the current one in the
// URL. Is is essential that we only intercept those from instant navigation
// events and not from history change events, or we'll end up in and endless
// loop. The top-level history entry must be removed, as it will be replaced
// with a new one, which would otherwise lead to a duplicate entry.
location$.pipe(
distinctUntilChanged((a, b) => (
a.pathname === b.pathname &&
a.hash === b.hash
)),
map(([, next]) => next)
switchMap(() => instant$),
tap(() => history.back())
)
)
.subscribe(url => {
// Check if the current history entry has a state, which happens when the
// user presses the back or forward button to visit a page we've already
// seen. If there's no state, it means a new page was visited and we must
// scroll to the top, unless an anchor is given.
if (history.state !== null || !url.hash) {
window.scrollTo(0, history.state?.y ?? 0)
} else {
@ -392,46 +394,27 @@ export function setupInstantNavigation(
}
})
// Intercept clicks on the same anchor link - we must use a distinct pipeline
// for this, or we'd end up in a loop, setting the hash again and again
location$
.pipe(
sample(instant$),
startWith(getLocation()),
bufferCount(2, 1),
filter(([prev, next]) => (
prev.pathname === next.pathname &&
prev.hash === next.hash
)),
map(([, next]) => next)
)
.subscribe(url => {
history.scrollRestoration = "auto"
setLocationHash(url.hash)
// Disable scroll restoration when an instant navigation event occurs, so the
// browser does not immediately set the viewport offset to the prior history
// entry, scrolling to the position on the same page, which would look odd.
// Instead, we manually restore the position once the page has loaded.
location$.subscribe(() => {
history.scrollRestoration = "manual"
// Hack: we need to make sure that we don't end up with multiple history
// entries for the same anchor link, so we just remove the last entry
history.back()
})
// After parsing the document, check if the current history entry has a state.
// This may happen when users press the back or forward button to visit a page
// that was already seen. If there's no state, it means a new page was visited
// and we should scroll to the top, unless an anchor is given.
document$.pipe(withLatestFrom(location$))
.subscribe(([, url]) => {
if (history.state !== null || !url.hash) {
window.scrollTo(0, history.state?.y ?? 0)
} else {
setLocationHash(url.hash)
}
// Enable scroll restoration before window unloads - this is essential to
// ensure that full reloads (F5) restore the viewport offset correctly. If
// only popstate events wouldn't reset the viewport offset prior to their
// emission, we could just reset this in popstate. Meh.
fromEvent(window, "beforeunload")
.subscribe(() => {
history.scrollRestoration = "auto"
})
// If the current history is not empty, register an event listener updating
// the current history state whenever the scroll position changes. This must
// be debounced and cannot be done in popstate, as popstate has already
// removed the entry from the history.
// Track viewport offset, so we can restore it when the user navigates back
// and forth between pages. Note that this must be debounced and cannot be
// done in popstate, as popstate has already removed the entry from the
// history, which means it is too late.
viewport$
.pipe(
distinctUntilKeyChanged("offset"),

5
src/templates/assets/javascripts/integrations/sitemap/.eslintrc Normal file
View File

@ -0,0 +1,5 @@
{
"rules": {
"no-null/no-null": "off"
}
}

111
src/templates/assets/javascripts/integrations/sitemap/index.ts
View File

@ -21,17 +21,17 @@
*/
import {
EMPTY,
Observable,
catchError,
defaultIfEmpty,
map,
of,
tap
of
} from "rxjs"
import { configuration } from "~/_"
import { getElements, requestXML } from "~/browser"
import {
getElement,
getElements,
requestXML
} from "~/browser"
/* ----------------------------------------------------------------------------
* Types
@ -40,41 +40,75 @@ import { getElements, requestXML } from "~/browser"
/**
* Sitemap, i.e. a list of URLs
*/
export type Sitemap = string[]
export type Sitemap = Map<string, URL[]>
/* ----------------------------------------------------------------------------
* Helper functions
* ------------------------------------------------------------------------- */
/**
* Preprocess a list of URLs
* Resolve URL to the given base URL
*
* This function replaces the `site_url` in the sitemap with the actual base
* URL, to allow instant navigation to work in occasions like Netlify previews.
* When serving the site with instant navigation, MkDocs will set the hostname
* to the value as specified in `dev_addr`, but the browser allows for several
* hostnames to be used: `localhost`, `127.0.0.1` or even `0.0.0.0`, depending
* on configuration. This function resolves the URL to the given hostname.
*
* @param urls - URLs
* @param url - URL
* @param base - Base URL
*
* @returns URL path parts
* @returns Resolved URL
*/
function preprocess(urls: Sitemap): Sitemap {
if (urls.length < 2)
return [""]
function resolve(url: URL, base: URL) {
url.protocol = base.protocol
url.hostname = base.hostname
return url
}
/* Take the first two URLs and remove everything after the last slash */
const [root, next] = [...urls]
.sort((a, b) => a.length - b.length)
.map(url => url.replace(/[^/]+$/, ""))
/**
* Extract sitemap from document
*
* This function extracts the URLs and alternate links from the document, and
* associates alternate links to the original URL as found in `loc`, allowing
* the browser to navigate to the correct page when switching languages. The
* format of the sitemap is expected to adhere to:
*
* ``` xml
* <urlset>
* <url>
* <loc>...</loc>
* <xhtml:link rel="alternate" hreflang="en" href="..."/>
* <xhtml:link rel="alternate" hreflang="de" href="..."/>
* ...
* </url>
* ...
* </urlset>
* ```
*
* @param document - Document
* @param base - Base URL
*
* @returns Sitemap
*/
function extract(document: Document, base: URL): Sitemap {
const sitemap: Sitemap = new Map()
for (const el of getElements("url", document)) {
const url = getElement("loc", el)
/* Compute common prefix */
let index = 0
if (root === next)
index = root.length
else
while (root.charCodeAt(index) === next.charCodeAt(index))
index++
// Create entry for location and add it to the list of links
const links = [resolve(new URL(url.textContent!), base)]
sitemap.set(`${links[0]}`, links)
/* Remove common prefix and return in original order */
return urls.map(url => url.replace(root.slice(0, index), ""))
// Attach alternate links to current entry
for (const link of getElements("[rel=alternate]", el)) {
const href = link.getAttribute("href")
if (href != null)
links.push(resolve(new URL(href), base))
}
}
// Return sitemap
return sitemap
}
/* ----------------------------------------------------------------------------
@ -84,24 +118,17 @@ function preprocess(urls: Sitemap): Sitemap {
/**
* Fetch the sitemap for the given base URL
*
* If a network or parsing error occurs, we just default to an empty sitemap,
* which means the caller should fall back to regular navigation.
*
* @param base - Base URL
*
* @returns Sitemap observable
*/
export function fetchSitemap(base?: URL): Observable<Sitemap> {
const cached = __md_get<Sitemap>("__sitemap", sessionStorage, base)
if (cached) {
return of(cached)
} else {
const config = configuration()
return requestXML(new URL("sitemap.xml", base || config.base))
export function fetchSitemap(base: URL | string): Observable<Sitemap> {
return requestXML(new URL("sitemap.xml", base))
.pipe(
map(sitemap => preprocess(getElements("loc", sitemap)
.map(node => node.textContent!)
)),
catchError(() => EMPTY), // @todo refactor instant loading
defaultIfEmpty([]),
tap(sitemap => __md_set("__sitemap", sitemap, sessionStorage, base))
map(document => extract(document, new URL(base))),
catchError(() => of(new Map())),
)
}
}

2
src/templates/assets/javascripts/integrations/version/index.ts
View File

@ -134,7 +134,7 @@ export function setupVersionSelector(
map(sitemap => {
const location = getLocation()
const path = location.href.replace(config.base, "")
return sitemap.includes(path.split("#")[0])
return sitemap.has(path.split("#")[0])
? new URL(`../${version}/${path}`, config.base)
: new URL(url)
})