Renamed modules into integrations

src/assets/javascripts/integrations/index.ts

@@ -0,0 +1,23 @@
+/*
+ * 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 "./search"

src/assets/javascripts/integrations/search/_/index.ts

@@ -0,0 +1,233 @@
+/*
+ * 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.
+ */
+
+import * as lunr from "expose-loader?lunr!lunr"
+
+import {
+  ArticleDocument,
+  SearchDocumentMap,
+  SectionDocument,
+  setupSearchDocumentMap
+} from "../document"
+import {
+  SearchHighlightFactoryFn,
+  setupSearchHighlighter
+} from "../highlight"
+
+/* ----------------------------------------------------------------------------
+ * Types
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Search index configuration
+ */
+export interface SearchIndexConfig {
+  lang: string[]                       /* Search languages */
+  separator: string                    /* Search separator */
+}
+
+/**
+ * Search index document
+ */
+export interface SearchIndexDocument {
+  location: string                     /* Document location */
+  title: string                        /* Document title */
+  text: string                         /* Document text */
+}
+
+/**
+ * Search index pipeline
+ */
+export interface SearchIndexPipeline {
+  trimmer: boolean                     /* Add trimmer to pipeline */
+  stopwords: boolean                   /* Add stopword filter to pipeline */
+}
+
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Search index options
+ *
+ * This interfaces describes the format of the `search_index.json` file which
+ * is automatically built by the MkDocs search plugin.
+ */
+export interface SearchIndexOptions {
+  config: SearchIndexConfig            /* Search index configuration */
+  docs: SearchIndexDocument[]          /* Search index documents */
+  pipeline?: SearchIndexPipeline       /* Search index pipeline */
+  index?: object | string              /* Prebuilt or serialized index */
+}
+
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Search result
+ */
+export interface SearchResult {
+  article: ArticleDocument             /* Article document */
+  sections: SectionDocument[]          /* Section documents */
+}
+
+/* ----------------------------------------------------------------------------
+ * Class
+ * ------------------------------------------------------------------------- */
+
+export class SearchIndex {
+
+  /**
+   * Search document mapping
+   *
+   * A mapping of URLs (including hash fragments) to the actual articles and
+   * sections of the documentation. The search document mapping must be created
+   * regardless of whether the index was prebuilt or not, as lunr itself will
+   * only store the actual index.
+   */
+  protected documents: SearchDocumentMap
+
+  /**
+   * Search highlight factory function
+   */
+  protected highlight: SearchHighlightFactoryFn
+
+  /**
+   * The lunr search index
+   */
+  protected index: lunr.Index
+
+  /**
+   * Create a search index
+   *
+   * @param options - Options
+   */
+  public constructor({ config, docs, pipeline, index }: SearchIndexOptions) {
+    this.documents = setupSearchDocumentMap(docs)
+    this.highlight = setupSearchHighlighter(config)
+
+    /* If no index was given, create it */
+    if (typeof index === "undefined") {
+      this.index = lunr(function() {
+        pipeline = pipeline || {
+          trimmer: true,
+          stopwords: true
+        }
+
+        /* Remove stemmer, as it cripples search experience */
+        this.pipeline.reset()
+        if (pipeline.trimmer)
+          this.pipeline.add(lunr.trimmer)
+        if (pipeline.stopwords)
+          this.pipeline.add(lunr.stopWordFilter)
+
+        /* Set up alternate search languages */
+        if (config.lang.length === 1 && config.lang[0] !== "en") {
+          this.use((lunr as any)[config.lang[0]])
+        } else if (config.lang.length > 1) {
+          this.use((lunr as any).multiLanguage(...config.lang))
+        }
+
+        /* Setup fields and reference */
+        this.field("title", { boost: 10 })
+        this.field("text")
+        this.ref("location")
+
+        /* Index documents */
+        for (const doc of docs)
+          this.add(doc)
+      })
+
+    /* Prebuilt or serialized index */
+    } else {
+      this.index = lunr.Index.load(
+        typeof index === "string"
+          ? JSON.parse(index)
+          : index
+      )
+    }
+  }
+
+  /**
+   * Search for matching documents
+   *
+   * The search index which MkDocs provides is divided up into articles, which
+   * contain the whole content of the individual pages, and sections, which only
+   * contain the contents of the subsections obtained by breaking the individual
+   * pages up at `h1` ... `h6`. As there may be many sections on different pages
+   * with indentical titles (for example within this very project, e.g. "Usage"
+   * or "Installation"), they need to be put into the context of the containing
+   * page. For this reason, section results are grouped within their respective
+   * articles which are the top-level results that are returned.
+   *
+   * @param query - Query string
+   *
+   * @return Search results
+   */
+  public search(query: string): SearchResult[] {
+    if (query) {
+      try {
+
+        /* Group sections by containing article */
+        const groups = this.index.search(query)
+          .reduce((results, result) => {
+            const document = this.documents.get(result.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) || [])
+              }
+            }
+            return results
+          }, new Map<string, lunr.Index.Result[]>())
+
+        /* Create highlighter for query */
+        const fn = this.highlight(query)
+
+        /* 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)
+          })
+        }))
+
+      /* Log errors to console (for now) */
+      } catch (err) {
+        // tslint:disable-next-line no-console
+        console.warn(`Invalid query: ${query} – see https://bit.ly/2s3ChXG`)
+      }
+    }
+
+    /* Return nothing in case of error or empty query */
+    return []
+  }
+
+  /**
+   * Serialize search index
+   *
+   * @return String representation
+   */
+  public toString(): string {
+    return JSON.stringify(this.index)
+  }
+}

src/assets/javascripts/integrations/search/document/index.ts

@@ -0,0 +1,117 @@
+/*
+ * 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.
+ */
+
+import * as escapeHTML from "escape-html"
+
+import { SearchIndexDocument } from "../_"
+
+/* ----------------------------------------------------------------------------
+ * Types
+ * ------------------------------------------------------------------------- */
+
+/**
+ * A top-level article
+ */
+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 */
+}
+
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Search document
+ */
+export type SearchDocument =
+  | ArticleDocument
+  | SectionDocument
+
+/**
+ * Search document mapping
+ */
+export type SearchDocumentMap = Map<string, SearchDocument>
+
+/* ----------------------------------------------------------------------------
+ * Functions
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Create a search document mapping
+ *
+ * @param docs - Search index documents
+ *
+ * @return Search document map
+ */
+export function setupSearchDocumentMap(
+  docs: SearchIndexDocument[]
+): SearchDocumentMap {
+  const documents = new Map<string, SearchDocument>()
+  for (const doc of docs) {
+    const [path, hash] = doc.location.split("#")
+
+    /* Extract location and title */
+    const location = doc.location
+    const title    = doc.title
+
+    /* Escape and cleanup text */
+    const text = escapeHTML(doc.text)
+      .replace(/\s+(?=[,.:;!?])/g, "")
+      .replace(/\s+/g, " ")
+
+    /* Handle section */
+    if (hash) {
+      const parent = documents.get(path) as ArticleDocument
+
+      /* Ignore first section, override article */
+      if (!parent.linked) {
+        parent.title  = doc.title
+        parent.text   = text
+        parent.linked = true
+
+      /* Add subsequent section */
+      } else {
+        documents.set(location, {
+          location,
+          title,
+          text,
+          parent
+        })
+      }
+
+    /* Add article */
+    } else {
+      documents.set(location, {
+        location,
+        title,
+        text,
+        linked: false
+      })
+    }
+  }
+  return documents
+}

src/assets/javascripts/integrations/search/highlight/index.ts

@@ -0,0 +1,91 @@
+/*
+ * 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.
+ */
+
+import * as escapeRegExp from "escape-string-regexp"
+
+import { SearchIndexConfig } from "../_"
+import { SearchDocument } from "../document"
+
+/* ----------------------------------------------------------------------------
+ * Types
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Search highlight function
+ *
+ * @template T - Search document type
+ *
+ * @param document - Search document
+ *
+ * @return Highlighted document
+ */
+export type SearchHighlightFn =
+  <T extends SearchDocument>(document: Readonly<T>) => T
+
+/**
+ * Search highlight factory function
+ *
+ * @param query - Query string
+ *
+ * @return Search highlight function
+ */
+export type SearchHighlightFactoryFn =
+  (query: string) => SearchHighlightFn
+
+/* ----------------------------------------------------------------------------
+ * Functions
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Create a search highlighter
+ *
+ * @param config - Search index configuration
+ *
+ * @return Search highlight factory function
+ */
+export function setupSearchHighlighter(
+  config: SearchIndexConfig
+): SearchHighlightFactoryFn {
+  const separator = new RegExp(config.separator, "img")
+  const highlight = (_: unknown, data: string, term: string) => {
+    return `${data}<em>${term}</em>`
+  }
+
+  /* Return factory function */
+  return (query: string) => {
+    query = query
+      .replace(/[\s*+-:~^]+/g, " ")
+      .trim()
+
+    /* Create search term match expression */
+    const match = new RegExp(`(^|${config.separator})(${
+      escapeRegExp(query).replace(separator, "|")
+    })`, "img")
+
+    /* Highlight document */
+    return document => ({
+      ...document,
+      title: document.title.replace(match, highlight),
+      text:  document.text.replace(match, highlight)
+    })
+  }
+}

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

@@ -0,0 +1,28 @@
+/*
+ * 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 {
+  ArticleDocument,
+  SearchDocument,
+  SectionDocument
+} from "./document"

src/assets/javascripts/integrations/source/github/index.ts

@@ -0,0 +1,102 @@
+/*
+ * 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.
+ */
+
+import { Repo, User } from "github-types"
+import { NEVER, Observable } from "rxjs"
+import { ajax } from "rxjs/ajax"
+import { filter, map, pluck, shareReplay } from "rxjs/operators"
+
+/* ----------------------------------------------------------------------------
+ * Helper functions
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Round a number
+ *
+ * TODO: document
+ */
+function round(value: number) {
+  return value > 999
+    ? `${(value / 1000).toFixed(1)}k`
+    : `${(value)}`
+}
+
+/**
+ * TODO: document
+ */
+export function fetchGitHubStats(
+  user: string
+): Observable<User>
+export function fetchGitHubStats(
+  user: string, repo: string
+): Observable<Repo>
+export function fetchGitHubStats(
+  user: string, repo?: string
+): Observable<User | Repo> {
+  const endpoint = typeof repo !== "undefined"
+    ? `repos/${user}/${repo}`
+    : `users/${user}`
+  return ajax({
+    url: `https://api.github.com/${endpoint}`,
+    responseType: "json"
+  })
+    .pipe(
+      filter(({ status }) => status === 200),
+      pluck("response"),
+      shareReplay(1)
+    )
+}
+
+// TODO: GitLab API:
+// https://docs.gitlab.com/ee/api/projects.html#get-single-project
+// curl "https://gitlab.com/api/v4/projects/johannes-z%2Fmkdocs-material"
+
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Get repository information
+ *
+ * TODO: document
+ */
+export function getRepository(user: string, repo: string): Observable<string[]> {
+  return fetchGitHubStats(user, repo)
+    .pipe(
+      map(({ stargazers_count, forks_count }) => ([
+        `${round(stargazers_count || 0)} Stars`,
+        `${round(forks_count || 0)} Forks`
+      ]))
+    )
+}
+
+/**
+ * Get user/organization information
+ *
+ * TODO: document
+ */
+export function getUser(user: string): Observable<string[]> {
+  return fetchGitHubStats(user)
+    .pipe(
+      map(({ public_repos }) => ([
+        `${round(public_repos || 0)} Repositories`
+      ]))
+    )
+}