docs: refactor docs to use VitePress

.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: Deploy GitHub Pages
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+      - 'package.json'
+    branches:
+      - 'main'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
+        with:
+          fetch-depth: 0
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@a3252b78c470c02df07e9d59298aecedc3ccdd6d # v3.0.0
+
+      - name: Set node version to 20
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Setup Pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
+
+      - name: Install deps
+        run: pnpm install
+
+      - name: Build with VitePress
+        run: pnpm run docs:build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
+        with:
+          path: ./docs/.vitepress/dist/
+
+  deploy-docs:
+    runs-on: ubuntu-latest
+    needs: build-docs
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

docs/.vitepress/config.mts

@@ -0,0 +1,192 @@
+import { DefaultTheme, defineConfig } from 'vitepress';
+
+import pkg from '../../package.json';
+
+const repository = 'https://github.com/salsita/node-pg-migrate';
+export default defineConfig({
+  title: 'node-pg-migrate',
+  description: 'PostgreSQL database migration management tool',
+  base: '/node-pg-migrate/', // for GitHub Pages
+  srcDir: 'src',
+  lastUpdated: true,
+  cleanUrls: true,
+  metaChunk: true,
+
+  themeConfig: {
+    nav: navBarItems(),
+    sidebar: sidebar(),
+
+    search: {
+      provider: 'local',
+    },
+
+    socialLinks: [
+      { icon: 'github', link: repository },
+      { icon: 'npm', link: 'https://www.npmjs.com/package/node-pg-migrate' },
+    ],
+
+    editLink: {
+      pattern: repository + '/edit/main/docs/src/:path',
+      text: 'Edit this page on GitHub',
+    },
+  },
+});
+
+function navBarItems(): DefaultTheme.NavItem[] {
+  return [
+    { text: 'Home', link: '/' },
+    { text: 'Getting Started', link: '/getting-started' },
+    {
+      text: 'Migrations',
+      link: '/migrations/',
+      activeMatch: `^/migrations/`,
+    },
+    {
+      text: pkg.version,
+      items: [
+        { text: 'Changelog', link: repository + '/blob/main/CHANGELOG.md' },
+        { text: 'Releases', link: repository + '/releases' },
+        { text: 'License', link: repository + '/blob/main/LICENSE' },
+      ],
+    },
+  ];
+}
+
+function sidebar(): DefaultTheme.Sidebar {
+  return [
+    {
+      base: '/',
+      text: 'Reference',
+      collapsed: false,
+      items: sidebarReference(),
+    },
+    {
+      base: '/migrations/',
+      text: 'Defining Migrations',
+      link: '/',
+      collapsed: false,
+      items: sidebarMigrations(),
+    },
+    {
+      base: '/faq/',
+      text: 'FAQ',
+      collapsed: false,
+      items: sidebarFAQ(),
+    },
+  ];
+}
+
+function sidebarReference(): DefaultTheme.SidebarItem[] {
+  return [
+    {
+      text: 'Introduction',
+      link: 'introduction',
+    },
+    {
+      text: 'Getting Started',
+      link: 'getting-started',
+    },
+    {
+      text: 'CLI',
+      link: 'cli',
+    },
+    {
+      text: 'Programmatic API',
+      link: 'api',
+    },
+  ];
+}
+
+function sidebarFAQ(): DefaultTheme.SidebarItem[] {
+  return [
+    {
+      text: 'Transpiling Migrations',
+      link: 'transpiling',
+    },
+    {
+      text: 'Troubleshooting',
+      link: 'troubleshooting',
+    },
+  ];
+}
+
+function sidebarMigrations(): DefaultTheme.SidebarItem[] {
+  return [
+    {
+      text: 'Tables',
+      link: 'tables',
+    },
+    {
+      text: 'Columns',
+      link: 'columns',
+    },
+    {
+      text: 'Constraints',
+      link: 'constraints',
+    },
+    {
+      text: 'Indexes',
+      link: 'indexes',
+    },
+    {
+      text: 'Functions',
+      link: 'functions',
+    },
+    {
+      text: 'Triggers',
+      link: 'triggers',
+    },
+    {
+      text: 'Schemas',
+      link: 'schemas',
+    },
+    {
+      text: 'Sequences',
+      link: 'sequences',
+    },
+    {
+      text: 'Views',
+      link: 'views',
+    },
+    {
+      text: 'Materialized Views',
+      link: 'mViews',
+    },
+    {
+      text: 'Types',
+      link: 'types',
+    },
+    {
+      text: 'Domains',
+      link: 'domains',
+    },
+    {
+      text: 'Operators',
+      link: 'operators',
+    },
+    {
+      text: 'Roles',
+      link: 'roles',
+    },
+    {
+      text: 'Policies',
+      link: 'policies',
+    },
+    {
+      text: 'Extensions',
+      link: 'extensions',
+    },
+    {
+      text: 'Grants',
+      link: 'grants',
+    },
+    {
+      text: 'Casts',
+      link: 'casts',
+    },
+    {
+      text: 'Miscellaneous',
+      link: 'misc',
+    },
+  ];
+}

docs/.vitepress/theme/index.ts

@@ -0,0 +1,17 @@
+// https://vitepress.dev/guide/custom-theme
+import type { Theme } from 'vitepress';
+import DefaultTheme from 'vitepress/theme';
+import { h } from 'vue';
+import './style.css';
+
+export default {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {
+      // https://vitepress.dev/guide/extending-default-theme#layout-slots
+    });
+  },
+  enhanceApp({ app, router, siteData }) {
+    // ...
+  },
+} satisfies Theme;

docs/.vitepress/theme/style.css

@@ -0,0 +1,123 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+:root {
+  --c-brown-1: #d26b38;
+  --c-brown-2: #e88d54;
+  --c-brown-3: #c27647;
+  --c-brown-soft-1: #a0623b;
+  --c-brown-soft-2: #2a2420;
+  --vp-c-brand-soft: #fbf6f4;
+}
+
+html.dark:root {
+  --vp-c-brand-soft: #2a2420;
+  --vp-c-bg-soft: #141414;
+  --vp-c-bg-alt: #121212;
+  --vp-c-bg-elv: #1b1b1b;
+  --vp-c-bg: #181818;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    78deg,
+    var(--c-brown-1) 40%,
+    var(--c-brown-2)
+  );
+}
+
+/**
+ * Component: Layout
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-c-brand-1: var(--c-brown-1);
+  --vp-c-brand-2: var(--c-brown-2);
+  --vp-c-brand-3: var(--c-brown-3);
+
+  --vp-c-default-1: var(--vp-c-gray-1);
+  --vp-c-default-2: var(--vp-c-gray-2);
+  --vp-c-default-3: var(--vp-c-gray-3);
+  --vp-c-default-soft: var(--vp-c-gray-soft);
+
+  --vp-c-tip-1: var(--vp-c-brand-1);
+  --vp-c-tip-2: var(--vp-c-brand-2);
+  --vp-c-tip-3: var(--vp-c-brand-3);
+  --vp-c-tip-soft: var(--vp-c-brand-soft);
+
+  --vp-c-warning-1: var(--vp-c-yellow-1);
+  --vp-c-warning-2: var(--vp-c-yellow-2);
+  --vp-c-warning-3: var(--vp-c-yellow-3);
+  --vp-c-warning-soft: var(--vp-c-yellow-soft);
+
+  --vp-c-danger-1: var(--vp-c-red-1);
+  --vp-c-danger-2: var(--vp-c-red-2);
+  --vp-c-danger-3: var(--vp-c-red-3);
+  --vp-c-danger-soft: var(--vp-c-red-soft);
+}
+
+/**
+ * Component: Button
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-text: var(--vp-c-white);
+  --vp-button-brand-bg: var(--vp-c-brand-3);
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-hover-text: var(--vp-c-white);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
+  --vp-button-brand-active-border: transparent;
+  --vp-button-brand-active-text: var(--vp-c-white);
+  --vp-button-brand-active-bg: var(--vp-c-brand-1);
+}
+
+/**
+ * Component: Home
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    var(--vp-c-brand-1) 30%,
+    var(--vp-c-brand-3)
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    var(--vp-c-brand-1) 50%,
+    var(--vp-c-brand-3) 50%
+  );
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(68px);
+  }
+}
+
+/**
+ * Component: Custom Block
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-custom-block-tip-border: transparent;
+  --vp-custom-block-tip-text: var(--vp-c-text-1);
+  --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
+  --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
+}
+
+/**
+ * Component: Algolia
+ * -------------------------------------------------------------------------- */
+
+.DocSearch {
+  --docsearch-primary-color: var(--vp-c-brand-1) !important;
+}