docs: new docs site (#147)

* new docs site

* update styles

* minor docs tweaks

* formatting

* feature cards

* update frontpage features

* add favicon

* update action

* typos

.github/workflows/publish.yml

@@ -1,12 +1,13 @@
 name: Build and Publish
 
 permissions:
-  contents: write
+  contents: write # for release
+  pages: write
+  id-token: write
 
 on:
   push:
-    branches:
-      - main
+    branches: [main]
 
 jobs:
   backend-tests:
@@ -57,19 +58,49 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.PUBLISH_TOKEN }}
 
-  deploy-docs:
-    name: Deploy docs
+  build-docs:
+    runs-on: ubuntu-latest
     needs:
       - goreleaser
-    runs-on: ubuntu-latest
     steps:
-      - name: Checkout main
-        uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Not needed if lastUpdated is not enabled
 
-      - name: Deploy docs
-        uses: mhausenblas/mkdocs-deploy-gh-pages@master
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          CONFIG_FILE: docs/mkdocs.yml
-          REQUIREMENTS: docs/requirements.txt
-          EXTRA_PACKAGES: build-base
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm # or pnpm / yarn
+          cache-dependency-path: "docs"
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Install dependencies
+        working-directory: docs
+        run: npm ci
+
+      - name: Build with VitePress
+        working-directory: docs
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/docs/.vitepress/dist
+
+  # Deployment job
+  deploy-docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs:
+      - build-docs
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -24,3 +24,8 @@ gen/
 go.work
 
 *.venv
+
+
+# Docs Stuff
+node_modules/
+docs/docs/.vitepress/cache/

docs/docs/.vitepress/config.mts

@@ -0,0 +1,71 @@
+import { defineConfig } from "vitepress";
+import { withMermaid } from "vitepress-plugin-mermaid";
+// https://vitepress.dev/reference/site-config
+export default withMermaid(
+  defineConfig({
+    title: "Scaffold",
+    description: "A Project and Template Scaffolding Tool",
+    head: [["link", { rel: "icon", href: "/favicon.webp" }]],
+    themeConfig: {
+      search: {
+        provider: "local",
+        options: {
+          detailedView: true,
+        },
+      },
+      // https://vitepress.dev/reference/default-theme-config
+      nav: [
+        { text: "Home", link: "/" },
+        { text: "Docs", link: "/introduction/what-is-scaffold" },
+      ],
+      outline: "deep",
+
+      sidebar: [
+        {
+          text: "Introduction",
+          items: [
+            {
+              text: "What is Scaffold?",
+              link: "/introduction/what-is-scaffold",
+            },
+            { text: "Quick Start", link: "/introduction/quick-start" },
+            { text: "Terminology", link: "/introduction/terminology" },
+          ],
+        },
+        {
+          text: "User Guide",
+          items: [
+            { text: "User Configuration", link: "/user-guide/scaffold-rc" },
+            {
+              text: "Scaffold Resolution",
+              link: "/user-guide/scaffold-resolution",
+            },
+            {
+              text: "Featured Scaffolds",
+              link: "/user-guide/featured-scaffolds",
+            },
+          ],
+        },
+        {
+          text: "Creating Scaffolds",
+          items: [
+            { text: "Scaffold File", link: "/templates/scaffold-file" },
+            { text: "Template Engine", link: "/templates/template-engine" },
+            {
+              text: "File Reference",
+              link: "/templates/config-reference",
+            },
+            {
+              text: "Testing Scaffolds",
+              link: "/templates/testing-scaffolds",
+            },
+          ],
+        },
+      ],
+
+      socialLinks: [
+        { icon: "github", link: "https://github.com/hay-kot/scaffold" },
+      ],
+    },
+  }),
+);

docs/docs/.vitepress/theme/index.ts

@@ -0,0 +1,17 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+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/docs/.vitepress/theme/style.css

@@ -0,0 +1,166 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
+ * Colors
+ *
+ * Each colors have exact same color scale system with 3 levels of solid
+ * colors with different brightness, and 1 soft color.
+ *
+ * - `XXX-1`: The most solid color used mainly for colored text. It must
+ *   satisfy the contrast ratio against when used on top of `XXX-soft`.
+ *
+ * - `XXX-2`: The color used mainly for hover state of the button.
+ *
+ * - `XXX-3`: The color for solid background, such as bg color of the button.
+ *   It must satisfy the contrast ratio with pure white (#ffffff) text on
+ *   top of it.
+ *
+ * - `XXX-soft`: The color used for subtle background such as custom container
+ *   or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
+ *   on top of it.
+ *
+ *   The soft color must be semi transparent alpha channel. This is crucial
+ *   because it allows adding multiple "soft" colors on top of each other
+ *   to create a accent, such as when having inline code block inside
+ *   custom containers.
+ *
+ * - `default`: The color used purely for subtle indication without any
+ *   special meanings attched to it such as bg color for menu hover state.
+ *
+ * - `brand`: Used for primary brand colors, such as link text, button with
+ *   brand theme, etc.
+ *
+ * - `tip`: Used to indicate useful information. The default theme uses the
+ *   brand color for this by default.
+ *
+ * - `warning`: Used to indicate warning to the users. Used in custom
+ *   container, badges, etc.
+ *
+ * - `danger`: Used to show error, or dangerous message to the users. Used
+ *   in custom container, badges, etc.
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --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-brand-1: #0284c7;
+  --vp-c-brand-2: #0369a1;
+  --vp-c-brand-3: #075985;
+  --vp-c-brand-soft: rgba(65, 209, 255, 0.1);
+
+  --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,
+    #41d1ff 30%,
+    #afe8f7
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    #47caff 50%,
+    #afe8f7 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);
+  }
+}
+
+@media (max-width: 640px) {
+  .VPImage.image-src {
+    max-width: 325px;
+    max-height: 220px;
+  }
+}
+
+@media (min-width: 640px) {
+  .VPImage.image-src {
+    max-width: 490px;
+    max-height: 300px;
+  }
+}
+
+@media (min-width: 960px) {
+  .VPImage.image-src {
+    max-width: 550px;
+    max-height: 300px;
+  }
+}
+
+@media (min-width: 1280px) {
+  .VPImage.image-src {
+    max-width: 700px;
+    max-height: 450px;
+  }
+}
+
+/**
+ * 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;
+}