chore: enhance docs

Author: chrisbbreuer

.vscode/settings.json

@@ -6,6 +6,11 @@
     "source.fixAll.eslint": "explicit",
     "source.organizeImports": "never"
   },
+  "eslint.options": {
+    "flags": [
+      "unstable_ts_config"
+    ]
+  },
   "eslint.rules.customizations": [
     { "rule": "style/*", "severity": "off", "fixable": true },
     { "rule": "format/*", "severity": "off", "fixable": true },

docs/.vitepress/components.d.ts

@@ -0,0 +1,16 @@
+/* eslint-disable */
+// @ts-nocheck
+// Generated by unplugin-vue-components
+// Read more: https://github.com/vuejs/core/pull/3399
+export {}
+
+/* prettier-ignore */
+declare module 'vue' {
+  export interface GlobalComponents {
+    Home: typeof import('./theme/components/Home.vue')['default']
+    HomeContributors: typeof import('./theme/components/HomeContributors.vue')['default']
+    HomeSponsors: typeof import('./theme/components/HomeSponsors.vue')['default']
+    HomeTeam: typeof import('./theme/components/HomeTeam.vue')['default']
+    TeamMember: typeof import('./theme/components/TeamMember.vue')['default']
+  }
+}

docs/.vitepress/config.ts

@@ -1,32 +1,170 @@
+import type { HeadConfig } from 'vitepress'
+import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
+import { withPwa } from '@vite-pwa/vitepress'
 import { defineConfig } from 'vitepress'
 
+import viteConfig from './vite.config'
+
 // https://vitepress.dev/reference/site-config
-export default defineConfig({
-  title: 'tlsx',
-  description: 'A simple, fast, and secure TLS certificate manager for your projects.',
-  cleanUrls: true,
-
-  themeConfig: {
-    // https://vitepress.dev/reference/default-theme-config
-    nav: [
-      { text: 'Docs', link: '/intro' },
-      { text: 'Changelog', link: 'https://github.com/stacksjs/tlsx/releases' },
-    ],
 
-    sidebar: [
+const analytics = {
+  driver: 'fathom',
+
+  drivers: {
+    googleAnalytics: {
+      trackingId: 'UA-XXXXXXXXX-X',
+    },
+
+    fathom: {
+      siteId: 'WOLZMJDL',
+    },
+  },
+}
+
+const fathomAnalyticsHead: HeadConfig[] = [
+  [
+    'script',
+    {
+      'src': 'https://cdn.usefathom.com/script.js',
+      'data-site': analytics.drivers?.fathom?.siteId || '',
+      'defer': '',
+    },
+  ],
+]
+
+const googleAnalyticsHead: HeadConfig[] = [
+  [
+    'script',
+    {
+      async: '',
+      src: `https://www.googletagmanager.com/gtag/js?id=${analytics.drivers?.googleAnalytics?.trackingId}`,
+    },
+  ],
+  [
+    'script',
+    {},
+    `window.dataLayer = window.dataLayer || [];
+      function gtag(){dataLayer.push(arguments);}
+      gtag('js', new Date());
+      gtag('config', 'TAG_ID');`,
+  ],
+]
+
+const nav = [
+  {
+    text: 'Changelog',
+    link: 'https://github.com/stacksjs/tlsx/blob/main/CHANGELOG.md',
+  },
+  // { text: 'Blog', link: 'https://updates.ow3.org' },
+  {
+    text: 'Resources',
+    items: [
+      { text: 'Team', link: '/team' },
+      { text: 'Sponsors', link: '/sponsors' },
+      { text: 'Partners', link: '/partners' },
+      { text: 'Postcardware', link: '/postcardware' },
       {
-        text: 'Get Started',
         items: [
-          { text: 'Introduction', link: '/intro' },
-          { text: 'Install', link: '/install' },
+          {
+            text: 'Awesome Stacks',
+            link: 'https://github.com/stacksjs/awesome-stacks',
+          },
+          {
+            text: 'Contributing',
+            link: 'https://github.com/stacksjs/stacks/blob/main/.github/CONTRIBUTING.md',
+          },
         ],
       },
     ],
+  },
+]
 
-    socialLinks: [
-      { icon: 'github', link: 'https://github.com/stacksjs/tlsx' },
-      { icon: 'bluesky', link: 'https://bsky.app/profile/chrisbreuer.dev' },
-      { icon: 'twitter', link: 'https://twitter.com/stacksjs' },
+const sidebar = [
+  {
+    text: 'Get Started',
+    items: [
+      { text: 'Introduction', link: '/intro' },
+      { text: 'Installation', link: '/install' },
     ],
   },
-})
+]
+
+const analyticsHead
+  = analytics.driver === 'fathom'
+    ? fathomAnalyticsHead
+    : analytics.driver === 'google-analytics'
+      ? googleAnalyticsHead
+      : []
+
+export default withPwa(
+  defineConfig({
+    lang: 'en-US',
+    title: 'Transport Layer Security',
+    description: 'A simple, fast, and secure TLS certificate manager for your projects.',
+    metaChunk: true,
+
+    head: [
+      ['link', { rel: 'icon', type: 'image/svg+xml', href: './images/logo-mini.svg' }],
+      ['link', { rel: 'icon', type: 'image/png', href: './images/logo.png' }],
+      ['meta', { name: 'theme-color', content: '#0A0ABC' }],
+      ['meta', { property: 'og:type', content: 'website' }],
+      ['meta', { property: 'og:locale', content: 'en' }],
+      ['meta', { property: 'og:title', content: 'Transport Layer Security | A better developer environment.' }],
+      ['meta', { property: 'og:site_name', content: 'Transport Layer Security' }],
+      ['meta', { property: 'og:image', content: './images/og-image.jpg' }],
+      ['meta', { property: 'og:url', content: 'https://tlsx.sh/' }],
+      // ['script', { 'src': 'https://cdn.usefathom.com/script.js', 'data-site': '', 'data-spa': 'auto', 'defer': '' }],
+      ...analyticsHead,
+    ],
+
+    themeConfig: {
+      logo: './images/logo-transparent.svg',
+
+      nav,
+      sidebar,
+
+      editLink: {
+        pattern: 'https://github.com/stacksjs/stacks/edit/main/docs/docs/:path',
+        text: 'Edit this page on GitHub',
+      },
+
+      footer: {
+        message: 'Released under the MIT License.',
+        copyright: 'Copyright © 2024-present Stacks.js, Inc.',
+      },
+
+      socialLinks: [
+        { icon: 'twitter', link: 'https://twitter.com/stacksjs' },
+        { icon: 'bluesky', link: 'https://bsky.app/profile/chrisbreuer.dev' },
+        { icon: 'github', link: 'https://github.com/stacksjs/tlsx' },
+        { icon: 'discord', link: 'https://discord.gg/stacksjs' },
+      ],
+
+      // algolia: services.algolia,
+
+      // carbonAds: {
+      //   code: '',
+      //   placement: '',
+      // },
+    },
+
+    pwa: {
+      manifest: {
+        theme_color: '#0A0ABC',
+      },
+    },
+
+    markdown: {
+      theme: {
+        light: 'vitesse-light',
+        dark: 'vitesse-dark',
+      },
+
+      codeTransformers: [
+        transformerTwoslash(),
+      ],
+    },
+
+    vite: viteConfig,
+  }),
+)

docs/.vitepress/sw.ts

@@ -0,0 +1,123 @@
+/// <reference types="vite/client" />
+
+/// <reference lib="webworker" />
+
+import { CacheableResponsePlugin } from 'workbox-cacheable-response'
+import { ExpirationPlugin } from 'workbox-expiration'
+import { cleanupOutdatedCaches, createHandlerBoundToURL, precacheAndRoute } from 'workbox-precaching'
+import { NavigationRoute, registerRoute } from 'workbox-routing'
+import { NetworkFirst, NetworkOnly, StaleWhileRevalidate } from 'workbox-strategies'
+
+declare let self: ServiceWorkerGlobalScope
+
+const entries = self.__WB_MANIFEST
+
+// self.__WB_MANIFEST is the default injection point
+precacheAndRoute(entries)
+
+// clean old assets
+cleanupOutdatedCaches()
+
+let allowlist: undefined | RegExp[]
+if (import.meta.env.DEV)
+  allowlist = [/^\/$/]
+
+if (import.meta.env.PROD) {
+  const swPath = self.location.pathname.lastIndexOf('/')
+  const base = swPath === 0 ? '/' : self.location.pathname.slice(0, swPath + 1)
+  function escapeStringRegexp(value: string) {
+    // Escape characters with special meaning either inside or outside character sets.
+    // Use a simple backslash escape when it’s always valid, and a `\xnn` escape when the simpler form would be disallowed by Unicode patterns’ stricter grammar.
+    return value
+      .replace(/[|\\{}()[\]^$+*?.]/g, '\\$&')
+      .replace(/-/g, '\\x2d')
+  }
+  allowlist = entries.filter((page) => {
+    return typeof page === 'string'
+      ? page.endsWith('.html')
+      : page.url.endsWith('.html')
+  }).map((page) => {
+    const url = typeof page === 'string' ? page : page.url
+    const regex = url === 'index.html'
+      ? escapeStringRegexp(base)
+      : escapeStringRegexp(`${base}${url.replace(/\.html$/, '')}`)
+    return new RegExp(`^${regex}(\\.html)?$`)
+  })
+  registerRoute(
+    ({ request, sameOrigin }) => {
+      return sameOrigin && request.mode === 'navigate'
+    },
+    new NetworkOnly({
+      plugins: [{
+        /* this callback will be called when the fetch call fails */
+        handlerDidError: async () => Response.redirect('404', 302),
+        /* this callback will prevent caching the response */
+        cacheWillUpdate: async () => null,
+      }],
+    }),
+    'GET',
+  )
+  // googleapis
+  registerRoute(
+    /^https:\/\/fonts\.googleapis\.com\/.*/i,
+    new NetworkFirst({
+      cacheName: 'google-fonts-cache',
+      plugins: [
+        new CacheableResponsePlugin({ statuses: [0, 200] }),
+        // we only need a few entries
+        new ExpirationPlugin({
+          maxEntries: 10,
+          maxAgeSeconds: 60 * 60 * 24 * 365, // <== 365 days
+        }),
+      ],
+    }),
+  )
+  // gstatic
+  registerRoute(
+    /^https:\/\/fonts\.gstatic\.com\/.*/i,
+    new StaleWhileRevalidate({
+      cacheName: 'google-fonts-cache',
+      plugins: [
+        new CacheableResponsePlugin({ statuses: [0, 200] }),
+        // we only need a few entries
+        new ExpirationPlugin({
+          maxEntries: 10,
+          maxAgeSeconds: 60 * 60 * 24 * 365, // <== 365 days
+        }),
+      ],
+    }),
+  )
+  // antfu sponsors
+  registerRoute(
+    /^https:\/\/cdn\.jsdelivr\.net\/.*/i,
+    new NetworkFirst({
+      cacheName: 'jsdelivr-images-cache',
+      plugins: [
+        new CacheableResponsePlugin({ statuses: [0, 200] }),
+        // we only need a few entries
+        new ExpirationPlugin({
+          maxEntries: 10,
+          maxAgeSeconds: 60 * 60 * 24 * 7, // <== 7 days
+        }),
+      ],
+    }),
+  )
+}
+
+// to allow work offline
+registerRoute(new NavigationRoute(
+  createHandlerBoundToURL('index.html'),
+  { allowlist },
+))
+
+// Skip-Waiting Service Worker-based solution
+self.addEventListener('activate', async () => {
+  // after we've taken over, iterate over all the current clients (windows)
+  const clients = await self.clients.matchAll({ type: 'window' })
+  clients.forEach((client) => {
+    // ...and refresh each one of them
+    client.navigate(client.url)
+  })
+})
+
+self.skipWaiting()

docs/.vitepress/theme/components/Home.vue

@@ -0,0 +1,9 @@
+<template>
+  <div class="flex flex-col items-center mt-4 home">
+    <HomeTeam />
+
+    <HomeSponsors />
+
+    <HomeContributors />
+  </div>
+</template>

docs/.vitepress/theme/components/HomeContributors.vue

@@ -0,0 +1,20 @@
+<script setup lang="ts">
+import { contributors } from './contributors'
+</script>
+
+<template>
+  <div class="vp-doc">
+    <h2 pb-2 pt-5 font-normal op50>
+      Contributors
+    </h2>
+  </div>
+
+  <div max-w-200 p-10 text-center text-lg leading-7>
+    <div flex="~ wrap gap-1" justify-center>
+      <a v-for="{ name, avatar } of contributors" :key="name" :href="`https://github.com/${name}`" m-0 rel="noopener noreferrer" :aria-label="`${name} on GitHub`">
+        <img loading="lazy" :src="avatar" width="40" height="40" h-10 min-h-10 min-w-10 w-10 rounded-full :alt="`${name}'s avatar`">
+      </a>
+    </div>
+    <br>
+  </div>
+</template>

docs/.vitepress/theme/components/HomeSponsors.vue

@@ -0,0 +1,19 @@
+<template>
+  <div class="vp-doc">
+    <h2 pb-2 pt-5 font-normal op50>
+      Stacks Sponsors
+    </h2>
+  </div>
+
+  <p id="sponsor" class="mt-5 text-center">
+    <a href="https://github.com/sponsors/chrisbbreuer">
+      <img src="https://cdn.jsdelivr.net/gh/stacksjs/sponsors/sponsorkit/sponsors.svg" class="m-auto">
+    </a>
+  </p>
+
+  <p class="mt-5 text-center">
+    <a href="https://github.com/sponsors/chrisbbreuer" class="text-xs italic">
+      Click here to become a sponsor.
+    </a>
+  </p>
+</template>