Merge pull request #5 from Avivbens/support-vitepress-docs

support vitepress docs
Avivbens · Jun 6, 2024 · dfcfbbf · dfcfbbf
2 parents f2ceb14 + abd3d9d
commit dfcfbbf
Show file tree

Hide file tree

Showing 31 changed files with 3,136 additions and 251 deletions.
diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
@@ -0,0 +1,74 @@
+name: Deploy VitePress Docs 📚
+
+on:
+    release:
+        types:
+            - released
+    push:
+        branches:
+            - master
+        paths:
+            - 'docs/**/*'
+            - '.github/workflows/deploy-docs.yaml'
+            - 'package.json'
+
+permissions:
+    contents: read
+    pages: write
+    id-token: write
+
+concurrency:
+    group: pages
+    cancel-in-progress: true
+
+jobs:
+    checks:
+        name: Checks 🧪
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+
+            - name: Checks 🧪
+              uses: ./.github/workflows/health-check
+
+    build:
+        name: Build 🔨
+        runs-on: ubuntu-latest
+        needs:
+            - checks
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+
+            - name: 🖥️ Setup Env
+              uses: ./.github/workflows/install
+
+            - name: Setup Pages
+              uses: actions/configure-pages@v5
+
+            - name: Build with VitePress
+              run: npm run docs:build
+
+            - name: Upload artifact
+              uses: actions/upload-pages-artifact@v3
+              with:
+                  path: 'dist/docs'
+
+    deploy:
+        name: Deploy 🚀
+        environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+        needs:
+            - build
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Deploy to GitHub Pages
+              id: deployment
+              uses: actions/deploy-pages@v4
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,58 +1,50 @@
 # [1.3.0](https://github.com/Avivbens/fast-alfred/compare/v1.2.1...v1.3.0) (2024-06-03)
 
-
 ### Features
 
-* support `fast-alfred` CLI 🚀 ([ac9811a](https://github.com/Avivbens/fast-alfred/commit/ac9811a3f947881e5d15c9e932f891cfa1f0de5e))
+-   support `fast-alfred` CLI 🚀 ([ac9811a](https://github.com/Avivbens/fast-alfred/commit/ac9811a3f947881e5d15c9e932f891cfa1f0de5e))
 
 ## [1.2.1](https://github.com/Avivbens/fast-alfred/compare/v1.2.0...v1.2.1) (2024-06-03)
 
-
 ### Bug Fixes
 
-* **configuration:** support `tabSize` option ([17b237b](https://github.com/Avivbens/fast-alfred/commit/17b237b15d968b4d9947e4a39d5c74492e85ef9e))
+-   **configuration:** support `tabSize` option ([17b237b](https://github.com/Avivbens/fast-alfred/commit/17b237b15d968b4d9947e4a39d5c74492e85ef9e))
 
 # [1.2.0](https://github.com/Avivbens/fast-alfred/compare/v1.1.3...v1.2.0) (2024-06-03)
 
-
 ### Features
 
-* **bundler:** support update `package.json` version too 🚀 ([46b4172](https://github.com/Avivbens/fast-alfred/commit/46b4172b2535d5ed7886f9328d18938edf9f8e6d))
+-   **bundler:** support update `package.json` version too 🚀 ([46b4172](https://github.com/Avivbens/fast-alfred/commit/46b4172b2535d5ed7886f9328d18938edf9f8e6d))
 
 ## [1.1.3](https://github.com/Avivbens/fast-alfred/compare/v1.1.2...v1.1.3) (2024-06-03)
 
-
 ### Bug Fixes
 
-* `pack` script get `targetDir` from config file, if exists 🏗️ ([8353241](https://github.com/Avivbens/fast-alfred/commit/83532412dc36d0625234fca071f2a00d9b314799))
+-   `pack` script get `targetDir` from config file, if exists 🏗️ ([8353241](https://github.com/Avivbens/fast-alfred/commit/83532412dc36d0625234fca071f2a00d9b314799))
 
 ## [1.1.2](https://github.com/Avivbens/fast-alfred/compare/v1.1.1...v1.1.2) (2024-06-03)
 
-
 ### Bug Fixes
 
-* better error handling and logs for reading configuration file 📂 ([3efc192](https://github.com/Avivbens/fast-alfred/commit/3efc1924971a4acbe03527a4ba718353219b5367))
+-   better error handling and logs for reading configuration file 📂 ([3efc192](https://github.com/Avivbens/fast-alfred/commit/3efc1924971a4acbe03527a4ba718353219b5367))
 
 ## [1.1.1](https://github.com/Avivbens/fast-alfred/compare/v1.1.0...v1.1.1) (2024-06-02)
 
-
 ### Bug Fixes
 
-* change config file to be commonjs - under `.fast-alfred.config.cjs` ❌ ([44982b4](https://github.com/Avivbens/fast-alfred/commit/44982b4a645d357b6e540b9670d7f0b32d32bc73))
+-   change config file to be commonjs - under `.fast-alfred.config.cjs` ❌ ([44982b4](https://github.com/Avivbens/fast-alfred/commit/44982b4a645d357b6e540b9670d7f0b32d32bc73))
 
 # [1.1.0](https://github.com/Avivbens/fast-alfred/compare/v1.0.0...v1.1.0) (2024-06-02)
 
-
 ### Features
 
-* support `workflowMetadata` configuration to update `info.plist` on new release 🥷 ([f8478ba](https://github.com/Avivbens/fast-alfred/commit/f8478ba4888e05263d97ecf682e709f6a101b8fc))
+-   support `workflowMetadata` configuration to update `info.plist` on new release 🥷 ([f8478ba](https://github.com/Avivbens/fast-alfred/commit/f8478ba4888e05263d97ecf682e709f6a101b8fc))
 
 # 1.0.0 (2024-06-02)
 
-
 ### Features
 
-* full API for `FastAlfred` - all basic needs for scripting 🥷 ([c069314](https://github.com/Avivbens/fast-alfred/commit/c06931430d9e346393c2fd6a4fbd2ef0ca9606ef))
-* support `fast-alfred` bundler 🔨 ([3713494](https://github.com/Avivbens/fast-alfred/commit/37134945225689258f7eeecb757fca75d5c0c7c7))
-* support bump-up versions for workflows 🚀 ([2a1aff1](https://github.com/Avivbens/fast-alfred/commit/2a1aff1567bb65768f52fad92f3120329ad0963a))
-* support dynamic user configuration by config file ✨ ([8ef8a77](https://github.com/Avivbens/fast-alfred/commit/8ef8a774d33c772680bb9cb9c31c4d7ead4fa4d9))
+-   full API for `FastAlfred` - all basic needs for scripting 🥷 ([c069314](https://github.com/Avivbens/fast-alfred/commit/c06931430d9e346393c2fd6a4fbd2ef0ca9606ef))
+-   support `fast-alfred` bundler 🔨 ([3713494](https://github.com/Avivbens/fast-alfred/commit/37134945225689258f7eeecb757fca75d5c0c7c7))
+-   support bump-up versions for workflows 🚀 ([2a1aff1](https://github.com/Avivbens/fast-alfred/commit/2a1aff1567bb65768f52fad92f3120329ad0963a))
+-   support dynamic user configuration by config file ✨ ([8ef8a77](https://github.com/Avivbens/fast-alfred/commit/8ef8a774d33c772680bb9cb9c31c4d7ead4fa4d9))
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Aviv Ben Shahar
+Copyright (c) 2024 Aviv Ben Shahar
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/SECURITY.md b/SECURITY.md
@@ -6,7 +6,7 @@ This table shows the current support over the package versions:
 
 | Version  | Supported          |
 | -------- | ------------------ |
-| >= 0.x | :white_check_mark: |
+| >= 1.x | :white_check_mark: |
 <!-- | >= 0.0.x | :x: | -->
 
 ## Reporting a Vulnerability

diff --git a/docs/.vitepress/.gitignore b/docs/.vitepress/.gitignore
@@ -0,0 +1 @@
+cache/**/*
diff --git a/docs/.vitepress/analytics/google-analytics.config.ts b/docs/.vitepress/analytics/google-analytics.config.ts
@@ -0,0 +1,7 @@
+export const GOOGLE_ANALYTICS_ID = 'G-STCMH1XZ54'
+export const GOOGLE_ANALYTICS_SCRIPT = `
+window.dataLayer = window.dataLayer || [];
+function gtag(){dataLayer.push(arguments);}
+gtag('js', new Date());
+gtag('config', '${GOOGLE_ANALYTICS_ID}');
+`
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -0,0 +1,55 @@
+import { defineConfig } from 'vitepress'
+// @ts-expect-error
+import { description } from '../../package.json'
+import { GOOGLE_ANALYTICS_ID, GOOGLE_ANALYTICS_SCRIPT } from './analytics/google-analytics.config'
+import { REPOSITORY_FULLNAME, getDocsBase, remoteDefaultBranch } from './constants/repository.mjs'
+import { NAVBAR } from './navbar.config.mjs'
+import { SIDEBAR } from './sidebar.config.mjs'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+    title: 'Fast Alfred',
+    description,
+    base: getDocsBase(),
+    cleanUrls: true,
+    ignoreDeadLinks: false,
+    outDir: '../dist/docs/',
+    head: [
+        // ['link', { rel: 'icon', href: 'favicon/favicon.ico' }],
+        // ['link', { rel: 'icon', type: 'image/png', sizes: '32x32', href: 'favicon/favicon-32x32.png' }],
+        // ['link', { rel: 'icon', type: 'image/png', sizes: '16x16', href: 'favicon/favicon-16x16.png' }],
+        // ['link', { rel: 'apple-touch-icon', sizes: '180x180', href: 'favicon/apple-touch-icon.png' }],
+        // ['link', { rel: 'manifest', href: 'favicon/site.webmanifest' }],
+        ['script', { async: '', src: `https://www.googletagmanager.com/gtag/js?id=${GOOGLE_ANALYTICS_ID}` }],
+        ['script', {}, GOOGLE_ANALYTICS_SCRIPT],
+    ],
+    markdown: {
+        defaultHighlightLang: 'typescript',
+        breaks: true,
+        lineNumbers: true,
+    },
+    appearance: 'force-dark',
+    themeConfig: {
+        // https://vitepress.dev/reference/default-theme-config
+        // logo: '/logos/logo-short-no-bg.png',
+        nav: NAVBAR,
+        sidebar: SIDEBAR,
+        // siteTitle: '',
+        socialLinks: [
+            //
+            { icon: 'github', link: `https://github.com/${REPOSITORY_FULLNAME}#readme` },
+        ],
+        search: { provider: 'local' },
+        editLink: {
+            pattern: `https://github.com/${REPOSITORY_FULLNAME}/edit/${remoteDefaultBranch}/docs/:path`,
+            text: 'Edit this page on GitHub',
+        },
+        lastUpdated: {
+            formatOptions: { dateStyle: 'medium' },
+        },
+        footer: {
+            message: 'Released under the MIT License',
+            copyright: 'Copyright © 2024-present Aviv Ben Shahar',
+        },
+    },
+})
diff --git a/docs/.vitepress/constants/repository.mts b/docs/.vitepress/constants/repository.mts
@@ -0,0 +1,37 @@
+import { execSync } from 'node:child_process'
+import { env } from 'node:process'
+
+const remoteOrigin =
+    env.GITHUB_SERVER_URL && env.GITHUB_REPOSITORY
+        ? `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}.git`
+        : execSync('git remote get-url origin').toString().trim()
+
+export const REMOTE_BASE_URL = new URL(remoteOrigin).origin
+
+export const REPOSITORY_LINK = remoteOrigin.replace(/\.git$/m, '')
+
+export const REPOSITORY_FULLNAME = env.GITHUB_REPOSITORY || remoteOrigin.match(/^https:\/\/.*\/(.*\/.*).git$/m)?.[1]
+
+export const getDocsBase = (): string => {
+    if (!env.CI) {
+        return `/pages/${REPOSITORY_FULLNAME}/`
+    }
+
+    const { GITHUB_REPOSITORY_OWNER: owner } = env
+
+    const repoName = REPOSITORY_FULLNAME?.replace(`${owner}/`, '')
+    return `/${repoName}/`
+}
+
+// TODO: dynamically get the default branch
+export const remoteDefaultBranch = 'master'
+
+if (!REMOTE_BASE_URL) {
+    throw new Error('Could not find remote base URL!')
+} else if (!REPOSITORY_LINK) {
+    throw new Error('Could not find repository link!')
+} else if (!REPOSITORY_FULLNAME) {
+    throw new Error('Could not find repository fullname!')
+} else if (!remoteDefaultBranch) {
+    throw new Error('Could not find remote default branch!')
+}
diff --git a/docs/.vitepress/navbar.config.mts b/docs/.vitepress/navbar.config.mts
@@ -0,0 +1,29 @@
+import { DefaultTheme } from 'vitepress'
+// @ts-expect-error
+import { version } from '../../package.json'
+import { REPOSITORY_FULLNAME } from './constants/repository.mjs'
+
+export const NAVBAR: DefaultTheme.NavItem[] = [
+    { text: 'Home', link: '/' },
+    {
+        text: version,
+        items: [
+            {
+                text: 'Changelog',
+                link: `https://github.com/${REPOSITORY_FULLNAME}/blob/v${version}/CHANGELOG.md`,
+            },
+            {
+                text: 'Contributing',
+                link: `https://github.com/${REPOSITORY_FULLNAME}/blob/v${version}/CONTRIBUTING.md`,
+            },
+            {
+                text: 'License',
+                link: `https://github.com/${REPOSITORY_FULLNAME}/blob/v${version}/LICENSE`,
+            },
+            {
+                text: 'Security',
+                link: `https://github.com/${REPOSITORY_FULLNAME}/blob/v${version}/SECURITY.md`,
+            },
+        ],
+    },
+]
diff --git a/docs/.vitepress/sidebar.config.mts b/docs/.vitepress/sidebar.config.mts
@@ -0,0 +1,68 @@
+import { DefaultTheme } from 'vitepress'
+
+export const SIDEBAR: DefaultTheme.Sidebar = [
+    {
+        text: 'Setup',
+        base: '/app/setup/',
+        link: '../quick-start',
+        collapsed: false,
+        items: [
+            {
+                text: 'Node.js Runtime 🚀',
+                link: 'runtime-explain',
+            },
+            {
+                text: 'Bundler Options 🏗️',
+                link: 'bundler-options',
+            },
+            {
+                text: 'Workflow Metadata 🥷',
+                link: 'workflow-metadata',
+            },
+            {
+                text: 'Versioning & Bundling 📦',
+                link: 'versioning-bundling',
+            },
+        ],
+    },
+    {
+        text: 'CI / CD 🐙',
+        base: '/app/ci/',
+        collapsed: false,
+        items: [
+            {
+                text: 'GitHub Actions 🤖',
+                link: 'github-actions',
+            },
+            {
+                text: 'Semantic Release 🚀',
+                link: 'semantic-release',
+            },
+        ],
+    },
+    {
+        text: 'Client',
+        base: '/app/client/',
+        link: 'client',
+    },
+    {
+        text: 'Troubleshooting',
+        base: '/app/troubleshooting/',
+        link: 'index',
+        collapsed: false,
+        items: [
+            {
+                text: 'Missing Config File',
+                link: 'missing-config-file',
+            },
+            {
+                text: 'Empty Glob',
+                link: 'empty-glob',
+            },
+            {
+                text: 'No Target Version 🎯',
+                link: 'no-target-version',
+            },
+        ],
+    },
+]