Migrate documentation to vitepress (knex#400)

Co-authored-by: Benicio Cardozo <[email protected]>

.gitignore

@@ -1,8 +1,2 @@
 node_modules
-npm-debug.log
-.idea
-.DS_Store
-.vagrant
-build/CHANGELOG.md
-build/version.js
-package-lock.json
+.vitepress/dist

.vitepress/config.ts

@@ -0,0 +1,105 @@
+import { defineConfig } from 'vitepress'
+import KnexDialectsPlugins from './knexDialects'
+
+export default defineConfig({
+  title: 'Knex.js',
+  description: 'Beta knex.js documentation.',
+  base: '/',
+  srcDir: 'src',
+  head: [
+    ["link", { rel: "icon", type: "image/png", href: "/knex-logo.png" }],
+  ],
+  themeConfig: {
+    logo: '/knex-logo.png',
+    repo: 'knex/knex',  
+    docsRepo: 'knex/documentation',  
+    docsDir: 'src',
+    docsBranch: 'main',
+    editLinks: true,
+    editLinkText: 'Edit this page on GitHub',
+    lastUpdated: 'Last Updated',
+    nav: [
+      { text: 'Guide', link: '/guide/', activeMatch: '^/guide/' },
+      {
+        text: 'F.A.Q.',
+        link: '/faq/',
+      },
+      {
+        text: 'Changelog',
+        link: '/changelog.html',
+      }
+    ],
+    sidebar: {
+      '/guide/': getGuideSidebar(),
+      '/faq/': getFaqSidebar(),
+    },
+    algolia: {
+      appId: 'V7E3EHUPD6',
+      apiKey: '44b5077836c1c8fba0f364383dde7fb4',
+      indexName: 'knex',
+      initialQuery: 'Installation',
+    }
+  },
+   vite: {
+     plugins: [
+       KnexDialectsPlugins()
+     ]
+   }
+})
+
+function getGuideSidebar() {
+  return [
+    {
+      text: 'Installation',
+      link: '/guide/'
+    },
+    {
+      text: 'Query Builder',
+      link: '/guide/query-builder'
+    },
+    {
+      text: 'Transactions',
+      link: '/guide/transactions'
+    },
+    {
+      text: 'Schema Builder',
+      link: '/guide/schema-builder'
+    },
+    {
+      text: 'Raw',
+      link: '/guide/raw'
+    },
+    {
+      text: 'Ref',
+      link: '/guide/ref'
+    },
+    {
+      text: 'Utility',
+      link: '/guide/utility'
+    },
+    {
+      text: 'Interfaces',
+      link: '/guide/interfaces'
+    },
+    {
+      text: 'Migrations',
+      link: '/guide/migrations'
+    },
+  ]
+}
+function getFaqSidebar() {
+  return [
+    {
+      text: 'F.A.Q.',
+      link: '/faq/'
+    },
+    {
+      text: 'Recipes',
+      link: '/faq/recipes'
+    },
+    {
+      text: 'Support',
+      link: '/faq/support'
+    },
+  ]
+}

.vitepress/knexDialects.ts

@@ -0,0 +1,47 @@
+
+import Knex from 'knex'
+import type { PluginOption } from 'vite'
+
+const dialects = {
+  'better-sqlite3': Knex({ client: 'better-sqlite3' }),
+  cockroachdb: Knex({ client: 'cockroachdb' }),
+  mssql: Knex({ client: 'mssql' }),
+  mysql: Knex({ client: 'mysql' }),
+  mysql2: Knex({ client: 'mysql2' }),
+  oracledb: Knex({ client: 'oracledb' }),
+  pgnative: Knex({ client: 'pgnative' }),
+  postgres: Knex({ client: 'postgres' }),
+  redshift: Knex({ client: 'redshift' }),
+  sqlite3: Knex({ client: 'sqlite3' }),
+}
+
+export default function knexDialects (): PluginOption {
+  const regex = /<SqlOutput[\s]*code="([^"]+)"[\s]*\/>/ig
+
+  return {
+    name: 'transform-file',
+    enforce: 'pre',
+
+    transform(src, id) {
+      if (id.endsWith('.md')) {
+        const matches = src.matchAll(regex)
+        for (const match of matches) {
+          let markdown = ''
+          const getCode = Function("knex", `return knex.raw(${match[1]});`);
+
+          for (const dialect in dialects) {
+            const knex = dialects[dialect]
+            const { sql } = getCode(knex)
+            const output = sql.toString()
+
+            markdown += `<div data-dialect="${dialect}">\n\n\`\`\`sql\n${output}\n\`\`\`\n\n</div>\n`
+          }
+
+          src = src.replace(match[0], markdown)
+        }
+      }
+
+      return src
+    }
+  }
+}

.vitepress/theme/AlgoliaSearchBox.vue

@@ -0,0 +1,172 @@
+<script setup lang="ts">
+import '@docsearch/css'
+import docsearch from '@docsearch/js'
+import { useRoute, useRouter, useData } from 'vitepress'
+import { getCurrentInstance, onMounted, watch } from 'vue'
+import type { DefaultTheme } from '../config'
+import type { DocSearchHit } from '@docsearch/react/dist/esm/types'
+const props = defineProps<{
+  options: DefaultTheme.AlgoliaSearchOptions
+  multilang?: boolean
+}>()
+const vm = getCurrentInstance()
+const route = useRoute()
+const router = useRouter()
+watch(
+  () => props.options,
+  (value) => {
+    update(value)
+  }
+)
+onMounted(() => {
+  initialize(props.options)
+})
+function isSpecialClick(event: MouseEvent) {
+  return (
+    event.button === 1 ||
+    event.altKey ||
+    event.ctrlKey ||
+    event.metaKey ||
+    event.shiftKey
+  )
+}
+function getRelativePath(absoluteUrl: string) {
+  const { pathname, hash } = new URL(absoluteUrl)
+  return pathname + hash
+}
+function update(options: any) {
+  if (vm && vm.vnode.el) {
+    vm.vnode.el.innerHTML =
+      '<div class="algolia-search-box" id="docsearch"></div>'
+    initialize(options)
+  }
+}
+const { lang } = useData()
+// if the user has multiple locales, the search results should be filtered
+// based on the language
+const facetFilters: string[] = props.multilang ? ['lang:' + lang.value] : []
+if (props.options.searchParameters?.facetFilters) {
+  facetFilters.push(...props.options.searchParameters.facetFilters)
+}
+watch(lang, (newLang, oldLang) => {
+  const index = facetFilters.findIndex((filter) => filter === 'lang:' + oldLang)
+  if (index > -1) {
+    facetFilters.splice(index, 1, 'lang:' + newLang)
+  }
+})
+function initialize(userOptions: any) {
+  docsearch(
+    Object.assign({}, userOptions, {
+      container: '#docsearch',
+      searchParameters: Object.assign({}, userOptions.searchParameters, {
+        // pass a custom lang facetFilter to allow multiple language search
+        // https://github.com/algolia/docsearch-configs/pull/3942
+        facetFilters
+      }),
+      navigator: {
+        navigate: ({ itemUrl }: { itemUrl: string }) => {
+          const { pathname: hitPathname } = new URL(
+            window.location.origin + itemUrl
+          )
+          // Router doesn't handle same-page navigation so we use the native
+          // browser location API for anchor navigation
+          if (route.path === hitPathname) {
+            window.location.assign(window.location.origin + itemUrl)
+          } else {
+            router.go(itemUrl)
+          }
+        }
+      },
+      transformItems: (items: DocSearchHit[]) => {
+        return items.map((item) => {
+          return Object.assign({}, item, {
+            url: getRelativePath(item.url)
+          })
+        })
+      },
+      hitComponent: ({
+        hit,
+        children
+      }: {
+        hit: DocSearchHit
+        children: any
+      }) => {
+        const relativeHit = hit.url.startsWith('http')
+          ? getRelativePath(hit.url as string)
+          : hit.url
+        return {
+          type: 'a',
+          ref: undefined,
+          constructor: undefined,
+          key: undefined,
+          props: {
+            href: hit.url,
+            onClick: (event: MouseEvent) => {
+              if (isSpecialClick(event)) {
+                return
+              }
+              // we rely on the native link scrolling when user is already on
+              // the right anchor because Router doesn't support duplicated
+              // history entries
+              if (route.path === relativeHit) {
+                return
+              }
+              // if the hits goes to another page, we prevent the native link
+              // behavior to leverage the Router loading feature
+              if (route.path !== relativeHit) {
+                event.preventDefault()
+              }
+              router.go(relativeHit)
+            },
+            children
+          },
+          __v: null
+        }
+      }
+    })
+  )
+}
+</script>
+
+<template>
+  <div class="algolia-search-box" id="docsearch" />
+</template>
+
+<style>
+.algolia-search-box {
+  padding-top: 1px;
+}
+@media (min-width: 720px) {
+  .algolia-search-box {
+    padding-left: 8px;
+  }
+}
+@media (min-width: 751px) {
+  .algolia-search-box {
+    min-width: 176.3px; /* avoid layout shift */
+  }
+  .algolia-search-box .DocSearch-Button-Placeholder {
+    padding-left: 8px;
+    font-size: 0.9rem;
+    font-weight: 500;
+  }
+}
+body .DocSearch {
+  --docsearch-primary-color: var(--c-brand);
+  --docsearch-modal-background: var(--c-white);
+  --docsearch-hit-background: var(--c-white-dark);
+  --docsearch-searchbox-focus-background: var(--c-white-dark);
+  --docsearch-highlight-color: var(--docsearch-primary-color);
+  --docsearch-searchbox-shadow: inset 0 0 0 2px var(--c-text-lighter);
+  --docsearch-hit-shadow: 0 1px 3px 0 var(--c-white);
+  --docsearch-text-color: var(--c-text);
+  --docsearch-muted-color: var(--c-text-dark-1);
+  --docsearch-searchbox-background: var(--c-white);
+  --docsearch-footer-background: var(--c-white);
+  --docsearch-modal-shadow: 0 3px 8px 0 var(--c-white-dark);
+  --docsearch-hit-color: var(--c-text);
+  --docsearch-footer-shadow: 0 -1px 0 0 var(--c-white-dark);
+  --docsearch-key-gradient: linear-gradient(-225deg,var(--c-white-dark),var(--c-white));
+  --docsearch-key-shadow: inset 0 -2px 0 0 var(--c-white-dark),inset 0 0 1px 1px var(--c-white),0 1px 2px 1px var(--c-white-darker);
+}
+</style>

.vitepress/theme/Layout.vue

@@ -0,0 +1,29 @@
+<script setup>
+import DefaultTheme from 'vitepress/theme'
+import { useData } from 'vitepress'
+import { computed, defineAsyncComponent } from 'vue'
+import SqlDialectSelector from "./SqlDialectSelector.vue";
+import ToggleDark from './ToggleDark.vue'
+
+const { Layout } = DefaultTheme
+const { site, theme } = useData()
+
+const AlgoliaSearchBox = defineAsyncComponent(() => import('./AlgoliaSearchBox.vue'))
+
+// automatic multilang check for AlgoliaSearchBox
+const isMultiLang = computed(() => Object.keys(site.value.langs).length > 1)
+</script>
+
+<template>
+  <Layout>
+    <template #navbar-search>
+      <SqlDialectSelector />
+      <AlgoliaSearchBox
+        v-if="theme.algolia"
+        :options="theme.algolia"
+        :multilang="isMultiLang"
+      />
+      <ToggleDark />     
+    </template>
+  </Layout>
+</template>