starred/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2026-07-24 06:43:50 -04:00
Code Issues Packages Projects Releases Wiki Activity

Funding goal reached: merged back new search UI/UX from Insiders

Browse Source
This commit is contained in:
squidfunk
2020-09-27 09:40:05 +02:00
parent 08318ac179
commit 8f61fd3b56
43 changed files with 696 additions and 315 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
src/assets/javascripts/integrations/keyboard/index.ts
View File

@@ -135,7 +135,10 @@ export function setupKeyboard(): Observable<Keyboard> {
if (typeof active === "undefined") {
setElementFocus(query)
} else {
const els = [query, ...getElements("[href]", result)]
const els = [query, ...getElements(
":not(details) > [href], summary, details[open] [href]",
result
)]
const i = Math.max(0, (
Math.max(0, els.indexOf(active)) + els.length + (
key.type === "ArrowUp" ? -1 : +1

113
src/assets/javascripts/integrations/search/_/index.ts
View File

@@ -21,15 +21,19 @@
*/
import {
ArticleDocument,
SearchDocument,
SearchDocumentMap,
SectionDocument,
setupSearchDocumentMap
} from "../document"
import {
SearchHighlightFactoryFn,
setupSearchHighlighter
} from "../highlighter"
import {
SearchQueryTerms,
getSearchQueryTerms,
parseSearchQuery
} from "../query"
/* ----------------------------------------------------------------------------
* Types
@@ -84,13 +88,22 @@ export interface SearchIndex {
/* ------------------------------------------------------------------------- */
/**
* Search metadata
*/
export interface SearchMetadata {
score: number /* Score (relevance) */
terms: SearchQueryTerms /* Search query terms */
}
/* ------------------------------------------------------------------------- */
/**
* Search result
*/
export interface SearchResult {
article: ArticleDocument /* Article document */
sections: SectionDocument[] /* Section documents */
}
export type SearchResult = Array<
SearchDocument & SearchMetadata
> // tslint:disable-line
/* ----------------------------------------------------------------------------
* Functions
@@ -116,7 +129,7 @@ function difference(a: string[], b: string[]): string[] {
* ------------------------------------------------------------------------- */
/**
* Search
* Search index
*
* Note that `lunr` is injected via Webpack, as it will otherwise also be
* bundled in the application bundle.
@@ -139,7 +152,7 @@ export class Search {
protected highlight: SearchHighlightFactoryFn
/**
* The `lunr` search index
* The underlying `lunr` search index
*/
protected index: lunr.Index
@@ -159,7 +172,7 @@ export class Search {
if (typeof index === "undefined") {
this.index = lunr(function() {
/* Set up alternate search languages */
/* Set up multi-language support */
if (config.lang.length === 1 && config.lang[0] !== "en") {
this.use((lunr as any)[config.lang[0]])
} else if (config.lang.length > 1) {
@@ -171,7 +184,7 @@ export class Search {
"trimmer", "stopWordFilter", "stemmer"
], pipeline!)
/* Remove functions from the pipeline for every language */
/* Remove functions from the pipeline for registered languages */
for (const lang of config.lang.map(language => (
language === "en" ? lunr : (lunr as any)[language]
))) {
@@ -191,7 +204,7 @@ export class Search {
this.add(doc)
})
/* Prebuilt or serialized index */
/* Handle prebuilt or serialized index */
} else {
this.index = lunr.Index.load(
typeof index === "string"
@@ -213,45 +226,71 @@ export class Search {
* page. For this reason, section results are grouped within their respective
* articles which are the top-level results that are returned.
*
* @param value - Query value
* @param query - Query value
*
* @return Search results
*/
public query(value: string): SearchResult[] {
if (value) {
public search(query: string): SearchResult[] {
if (query) {
try {
const highlight = this.highlight(query)
/* Group sections by containing article */
const groups = this.index.search(value)
.reduce((results, result) => {
const document = this.documents.get(result.ref)
/* Parse query to extract clauses for analysis */
const clauses = parseSearchQuery(query)
.filter(clause => (
clause.presence !== lunr.Query.presence.PROHIBITED
))
/* Perform search and post-process results */
const groups = this.index.search(`${query}*`)
/* Apply post-query boosts based on title and search query terms */
.reduce<SearchResult>((results, { ref, score, matchData }) => {
const document = this.documents.get(ref)
if (typeof document !== "undefined") {
if ("parent" in document) {
const ref = document.parent.location
results.set(ref, [...results.get(ref) || [], result])
} else {
const ref = document.location
results.set(ref, results.get(ref) || [])
}
const { location, title, text, parent } = document
/* Compute and analyze search query terms */
const terms = getSearchQueryTerms(
clauses,
Object.keys(matchData.metadata)
)
/* Highlight title and text and apply post-query boosts */
const boost = +!parent + +Object.values(terms).every(t => t)
results.push({
location,
title: highlight(title),
text: highlight(text),
score: score * (1 + boost),
terms
})
}
return results
}, new Map<string, lunr.Index.Result[]>())
}, [])
/* Create highlighter for query */
const fn = this.highlight(value)
/* Sort search results again after applying boosts */
.sort((a, b) => b.score - a.score)
/* Map groups to search documents */
return [...groups].map(([ref, sections]) => ({
article: fn(this.documents.get(ref) as ArticleDocument),
sections: sections.map(section => {
return fn(this.documents.get(section.ref) as SectionDocument)
})
}))
/* Group search results by page */
.reduce((results, result) => {
const document = this.documents.get(result.location)
if (typeof document !== "undefined") {
const ref = "parent" in document
? document.parent!.location
: document.location
results.set(ref, [...results.get(ref) || [], result])
}
return results
}, new Map<string, SearchResult>())
/* Expand grouped search results */
return [...groups.values()]
/* Log errors to console (for now) */
} catch (err) {
} catch {
// tslint:disable-next-line no-console
console.warn(`Invalid query: ${value} – see https://bit.ly/2s3ChXG`)
console.warn(`Invalid query: ${query} – see https://bit.ly/2s3ChXG`)
}
}

36
src/assets/javascripts/integrations/search/document/index.ts
View File

@@ -29,28 +29,14 @@ import { SearchIndexDocument } from "../_"
* ------------------------------------------------------------------------- */
/**
* A top-level article
* Search document
*/
export interface ArticleDocument extends SearchIndexDocument {
linked: boolean /* Whether the section was linked */
}
/**
* A section of an article
*/
export interface SectionDocument extends SearchIndexDocument {
parent: ArticleDocument /* Parent article */
export interface SearchDocument extends SearchIndexDocument {
parent?: SearchIndexDocument /* Parent article */
}
/* ------------------------------------------------------------------------- */
/**
* Search document
*/
export type SearchDocument =
| ArticleDocument
| SectionDocument
/**
* Search document mapping
*/
@@ -71,6 +57,7 @@ export function setupSearchDocumentMap(
docs: SearchIndexDocument[]
): SearchDocumentMap {
const documents = new Map<string, SearchDocument>()
const parents = new Set<SearchDocument>()
for (const doc of docs) {
const [path, hash] = doc.location.split("#")
@@ -85,13 +72,15 @@ export function setupSearchDocumentMap(
/* Handle section */
if (hash) {
const parent = documents.get(path) as ArticleDocument
const parent = documents.get(path)!
/* Ignore first section, override article */
if (!parent.linked) {
parent.title = doc.title
parent.text = text
parent.linked = true
if (!parents.has(parent)) {
parent.title = doc.title
parent.text = text
/* Remember that we processed the article */
parents.add(parent)
/* Add subsequent section */
} else {
@@ -108,8 +97,7 @@ export function setupSearchDocumentMap(
documents.set(location, {
location,
title,
text,
linked: false
text
})
}
}

33
src/assets/javascripts/integrations/search/highlighter/index.ts
View File

@@ -21,7 +21,6 @@
*/
import { SearchIndexConfig } from "../_"
import { SearchDocument } from "../document"
/* ----------------------------------------------------------------------------
* Types
@@ -30,24 +29,20 @@ import { SearchDocument } from "../document"
/**
* Search highlight function
*
* @template T - Search document type
* @param value - Value
*
* @param document - Search document
*
* @return Highlighted document
* @return Highlighted value
*/
export type SearchHighlightFn = <
T extends SearchDocument
>(document: Readonly<T>) => T
export type SearchHighlightFn = (value: string) => string
/**
* Search highlight factory function
*
* @param value - Query value
* @param query - Query value
*
* @return Search highlight function
*/
export type SearchHighlightFactoryFn = (value: string) => SearchHighlightFn
export type SearchHighlightFactoryFn = (query: string) => SearchHighlightFn
/* ----------------------------------------------------------------------------
* Functions
@@ -65,27 +60,25 @@ export function setupSearchHighlighter(
): SearchHighlightFactoryFn {
const separator = new RegExp(config.separator, "img")
const highlight = (_: unknown, data: string, term: string) => {
return `${data}<em>${term}</em>`
return `${data}<mark data-md-highlight>${term}</mark>`
}
/* Return factory function */
return (value: string) => {
value = value
return (query: string) => {
query = query
.replace(/[\s*+\-:~^]+/g, " ")
.trim()
/* Create search term match expression */
const match = new RegExp(`(^|${config.separator})(${
value
query
.replace(/[|\\{}()[\]^$+*?.-]/g, "\\$&")
.replace(separator, "|")
})`, "img")
/* Highlight document */
return document => ({
...document,
title: document.title.replace(match, highlight),
text: document.text.replace(match, highlight)
})
/* Highlight string value */
return value => value
.replace(match, highlight)
.replace(/<\/mark>(\s+)<mark[^>]*>/img, "\$1")
}
}

2
src/assets/javascripts/integrations/search/index.ts
View File

@@ -23,5 +23,5 @@
export * from "./_"
export * from "./document"
export * from "./highlighter"
export * from "./transform"
export * from "./query"
export * from "./worker"

92
src/assets/javascripts/integrations/search/query/_/index.ts Normal file
View File

@@ -0,0 +1,92 @@
/*
* Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to
* deal in the Software without restriction, including without limitation the
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
* sell copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
* IN THE SOFTWARE.
*/
/* ----------------------------------------------------------------------------
* Types
* ------------------------------------------------------------------------- */
/**
* Search query clause
*/
export interface SearchQueryClause {
presence: lunr.Query.presence /* Clause presence */
term: string /* Clause term */
}
/* ------------------------------------------------------------------------- */
/**
* Search query terms
*/
export type SearchQueryTerms = Record<string, boolean>
/* ----------------------------------------------------------------------------
* Functions
* ------------------------------------------------------------------------- */
/**
* Parse a search query for analysis
*
* @param value - Query value
*
* @return Search query clauses
*/
export function parseSearchQuery(
value: string
): SearchQueryClause[] {
const query = new (lunr as any).Query(["title", "text"])
const parser = new (lunr as any).QueryParser(value, query)
/* Parse and return query clauses */
parser.parse()
return query.clauses
}
/**
* Analyze the search query clauses in regard to the search terms found
*
* @param query - Search query clauses
* @param terms - Search terms
*
* @return Search query terms
*/
export function getSearchQueryTerms(
query: SearchQueryClause[], terms: string[]
): SearchQueryTerms {
const clauses = new Set<SearchQueryClause>(query)
/* Match query clauses against terms */
const result: SearchQueryTerms = {}
for (let t = 0; t < terms.length; t++)
for (const clause of clauses)
if (terms[t].startsWith(clause.term)) {
result[clause.term] = true
clauses.delete(clause)
}
/* Annotate unmatched query clauses */
for (const clause of clauses)
result[clause.term] = false
/* Return query terms */
return result
}

24
src/assets/javascripts/integrations/search/query/index.ts Normal file
View File

@@ -0,0 +1,24 @@
/*
* Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to
* deal in the Software without restriction, including without limitation the
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
* sell copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
* IN THE SOFTWARE.
*/
export * from "./_"
export * from "./transform"

14
src/assets/javascripts/integrations/search/transform/index.ts → src/assets/javascripts/integrations/search/query/transform/index.ts
View File

@@ -54,24 +54,18 @@ export type SearchTransformFn = (value: string) => string
*
* 3. Trim excess whitespace from left and right.
*
* 4. Append a wildcard to the end of every word to make every word a prefix
* query in order to provide a good typeahead experience, by adding an
* asterisk (wildcard) in between terms, which can be denoted by whitespace,
* any non-control character, or a word boundary.
*
* @param value - Query value
* @param query - Query value
*
* @return Transformed query value
*/
export function defaultTransform(value: string): string {
return value
export function defaultTransform(query: string): string {
return query
.split(/"([^"]+)"/g) /* => 1 */
.map((terms, i) => i & 1
.map((terms, index) => index & 1
? terms.replace(/^\b|^(?![^\x00-\x7F]|$)|\s+/g, " +")
: terms
)
.join("")
.replace(/"|(?:^|\s+)[*+\-:^~]+(?=\s+|$)/g, "") /* => 2 */
.trim() /* => 3 */
.replace(/\s+|(?![^\x00-\x7F]|^)$|\b$/g, "* ") /* => 4 */
}

48
src/assets/javascripts/integrations/search/worker/_/index.ts
View File

@@ -20,7 +20,6 @@
* IN THE SOFTWARE.
*/
import { identity } from "ramda"
import { Observable, Subject, asyncScheduler } from "rxjs"
import {
map,
@@ -30,9 +29,8 @@ import {
} from "rxjs/operators"
import { WorkerHandler, watchWorker } from "browser"
import { translate } from "utilities"
import { SearchIndex, SearchIndexPipeline } from "../../_"
import { SearchIndex } from "../../_"
import {
SearchMessage,
SearchMessageType,
@@ -52,38 +50,6 @@ interface SetupOptions {
base$: Observable<string> /* Location base observable */
}
/* ----------------------------------------------------------------------------
* Helper functions
* ------------------------------------------------------------------------- */
/**
* Set up search index
*
* @param data - Search index
*
* @return Search index
*/
function setupSearchIndex(
{ config, docs, index }: SearchIndex
): SearchIndex {
/* Override default language with value from translation */
if (config.lang.length === 1 && config.lang[0] === "en")
config.lang = [translate("search.config.lang")]
/* Override default separator with value from translation */
if (config.separator === "[\\s\\-]+")
config.separator = translate("search.config.separator")
/* Set pipeline from translation */
const pipeline = translate("search.config.pipeline")
.split(/\s*,\s*/)
.filter(identity) as SearchIndexPipeline
/* Return search index after defaulting */
return { config, docs, index, pipeline }
}
/* ----------------------------------------------------------------------------
* Functions
* ------------------------------------------------------------------------- */
@@ -112,11 +78,9 @@ export function setupSearchWorker(
withLatestFrom(base$),
map(([message, base]) => {
if (isSearchResultMessage(message)) {
for (const { article, sections } of message.data) {
article.location = `${base}/${article.location}`
for (const section of sections)
section.location = `${base}/${section.location}`
}
for (const result of message.data)
for (const document of result)
document.location = `${base}/${document.location}`
}
return message
}),
@@ -126,9 +90,9 @@ export function setupSearchWorker(
/* Set up search index */
index$
.pipe(
map<SearchIndex, SearchSetupMessage>(index => ({
map<SearchIndex, SearchSetupMessage>(data => ({
type: SearchMessageType.SETUP,
data: setupSearchIndex(index)
data
})),
observeOn(asyncScheduler)
)

76
src/assets/javascripts/integrations/search/worker/main/index.ts
View File

@@ -22,31 +22,74 @@
import "lunr"
import { Search, SearchIndexConfig } from "../../_"
import { SearchMessage, SearchMessageType } from "../message"
import {
Search,
SearchIndex,
SearchIndexConfig
} from "../../_"
import {
SearchMessage,
SearchMessageType
} from "../message"
/* ----------------------------------------------------------------------------
* Types
* ------------------------------------------------------------------------- */
/**
* Add support for usage with `iframe-worker` polyfill
*
* While `importScripts` is synchronous when executed inside of a webworker,
* it's not possible to provide a synchronous polyfilled implementation. The
* cool thing is that awaiting a non-Promise is a noop, so extending the type
* definition to return a `Promise` shouldn't break anything.
*
* @see https://bit.ly/2PjDnXi - GitHub comment
*/
declare global {
function importScripts(...urls: string[]): Promise<void> | void
}
/* ----------------------------------------------------------------------------
* Data
* ------------------------------------------------------------------------- */
/**
* Search
* Search index
*/
let search: Search
let index: Search
/* ----------------------------------------------------------------------------
* Helper functions
* ------------------------------------------------------------------------- */
/**
* Set up multi-language support through `lunr-languages`
* Fetch search index from given URL
*
* @param url - Search index URL
*
* @return Promise resolving with search index
*/
async function fetchSearchIndex(url: string): Promise<SearchIndex> {
return fetch(url, {
credentials: "same-origin"
})
.then(res => res.json())
}
/**
* Fetch (= import) multi-language support through `lunr-languages`
*
* This function will automatically import the stemmers necessary to process
* the languages which were given through the search index configuration.
*
* @param config - Search index configuration
*
* @return Promise resolving with no result
*/
function setupLunrLanguages(config: SearchIndexConfig): void {
async function setupSearchLanguages(
config: SearchIndexConfig
): Promise<void> {
const base = "../lunr"
/* Add scripts for languages */
@@ -62,7 +105,7 @@ function setupLunrLanguages(config: SearchIndexConfig): void {
/* Load scripts synchronously */
if (scripts.length)
importScripts(
await importScripts(
`${base}/min/lunr.stemmer.support.min.js`,
...scripts
)
@@ -79,13 +122,20 @@ function setupLunrLanguages(config: SearchIndexConfig): void {
*
* @return Target message
*/
export function handler(message: SearchMessage): SearchMessage {
export async function handler(
message: SearchMessage
): Promise<SearchMessage> {
switch (message.type) {
/* Search setup message */
case SearchMessageType.SETUP:
setupLunrLanguages(message.data.config)
search = new Search(message.data)
const data = typeof message.data === "string"
? await fetchSearchIndex(message.data)
: message.data
/* Set up search index with multi-language support */
await setupSearchLanguages(data.config)
index = new Search(data)
return {
type: SearchMessageType.READY
}
@@ -94,7 +144,7 @@ export function handler(message: SearchMessage): SearchMessage {
case SearchMessageType.QUERY:
return {
type: SearchMessageType.RESULT,
data: search ? search.query(message.data) : []
data: index ? index.search(message.data) : []
}
/* All other messages */
@@ -107,6 +157,6 @@ export function handler(message: SearchMessage): SearchMessage {
* Worker
* ------------------------------------------------------------------------- */
addEventListener("message", ev => {
postMessage(handler(ev.data))
addEventListener("message", async ev => {
postMessage(await handler(ev.data))
})

2
src/assets/javascripts/integrations/search/worker/message/index.ts
View File

@@ -43,7 +43,7 @@ export const enum SearchMessageType {
*/
export interface SearchSetupMessage {
type: SearchMessageType.SETUP /* Message type */
data: SearchIndex /* Message data */
data: SearchIndex | string /* Message data */
}
/**