docs: add vitepress and basic docs on testing (#75)

* Some docs on testing * Info on profiles * docs: add vitepress * fix: base --------- Co-authored-by: Northword <[email protected]>
northword · Dec 18, 2024 · c57f634 · c57f634
1 parent 9266dea
commit c57f634
Show file tree

Hide file tree

Showing 14 changed files with 1,690 additions and 179 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,68 @@
+name: docs
+
+on:
+  # Runs on pushes targeting the `main` branch. Change this to `master` if you're
+  # using the `master` branch as the default branch.
+  push:
+    branches: [main]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Not needed if lastUpdated is not enabled
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build with VitePress
+        run: pnpm docs:build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -5,4 +5,8 @@ node_modules
 
 dist
 build
-.npmrc
+.npmrc
+
+# vitepress
+docs/.vitepress/dist
+docs/.vitepress/cache
diff --git a/README.md b/README.md
@@ -14,132 +14,9 @@ This project is under active development, and some APIs may change. However, it
 
 For best practices regarding this package, please refer to [zotero-plugin-template](https://github.com/windingwind/zotero-plugin-template).
 
-## Using in a blank project
+## Documentation
 
-<details>
-
-<summary>WIP: Not yet implemented</summary>
-
-```bash
-# npm
-npx zotero-plugin create
-# pnpm
-pnpm dlx zotero-plugin create
-```
-
-</details>
-
-## Using in an existing project
-
-### 01. Install
-
-#### From NPM
-
-```bash
-npm install -D zotero-plugin-scaffold
-
-yarn add -D zotero-plugin-scaffold
-
-pnpm add -D zotero-plugin-scaffold
-```
-
-#### From source code
-
-```bash
-# clone this repo
-git clone https://github.com/northword/zotero-plugin-scaffold.git zotero-plugin-scaffold/
-cd zotero-plugin-scaffold/
-
-# build
-pnpm install
-pnpm build # or pnpm dev
-
-# npm link
-cd your-plugin-work-dir/
-pnpm link ../zotero-plugin-scaffold
-```
-
-### 02. Create a config file
-
-The configuration file needs to be stored in the following location.
-
-```bash
-zotero-plugin.config.ts  # also avaliable in *.js  *.mjs  *.cjs  *.ts
-```
-
-You can import helper `defineConfig` to get type hints. If no value is specified for an optional property, the default value will be used.
-
-```ts
-import { defineConfig } from "zotero-plugin-scaffold";
-
-export default defineConfig({
-  name: "the plugin name",
-  id: "the plugin id",
-  namespace: "the plugin namespace",
-  build: {
-    esbuildOptions: [
-      {
-        entryPoints: ["src/index.ts"],
-        bundle: true,
-        target: "firefox115",
-      },
-    ],
-  },
-});
-```
-
-Full config please refrence in [src/types](./src/types/index.ts).
-
-### 03. Create a env file
-
-This file defines Zotero's runtime configuration such as binary paths, profile paths, and environment variables required for Node scripts to run.
-
-NOTE: Do not check-in this file to the repository!
-
-```bash
-.env
-```
-
-```ini
-# The path of the Zotero binary file.
-# The path is `*/Zotero.app/Contents/MacOS/zotero` for macOS.
-ZOTERO_PLUGIN_ZOTERO_BIN_PATH = /path/to/zotero.exe
-
-# The path of the profile used for development.
-# Start the profile manager by `/path/to/zotero.exe -p` to create a profile for development.
-# @see https://www.zotero.org/support/kb/profile_directory
-ZOTERO_PLUGIN_PROFILE_PATH = /path/to/profile
-```
-
-### 04. Add scripts to package.json
-
-```json
-{
-  "scripts": {
-    "start": "zotero-plugin serve",
-    "build": "zotero-plugin build",
-    "release": "zotero-plugin release"
-  }
-}
-```
-
-### 05. Run
-
-```bash
-pnpm run start
-pnpm run build
-```
-
-## Using in NodeJS code
-
-```ts
-import { Build, Config } from "zotero-plugin-scaffold";
-
-const config = await Config.loadConfig();
-
-const Builder = new Build(config);
-await Builder.run();
-```
+[Read the Docs to Learn More.](https://northword.github.io/zotero-plugin-scaffold)
 
 ## Contributing
 

diff --git a/docs/.vitepress/.gitkeep b/docs/.vitepress/.gitkeep
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -0,0 +1,27 @@
+import { defineConfig } from "vitepress";
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Zotero Plugin Scaffold",
+  description: "Delivering a Modern and Elegant Development Experience for Zotero Plugins.",
+  base: "/zotero-plugin-scaffold/",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: "Home", link: "/" },
+    ],
+
+    sidebar: [
+      { text: "Why", link: "/why" },
+      { text: "Quick Start", link: "/quick-start" },
+      { text: "Serve", link: "/serve" },
+      { text: "Build", link: "/build" },
+      { text: "Test", link: "/test" },
+      { text: "Release", link: "/release" },
+    ],
+
+    socialLinks: [
+      { icon: "github", link: "https://github.com/northword/zotero-plugin-scaffold" },
+    ],
+  },
+});
diff --git a/docs/build.md b/docs/build.md
@@ -0,0 +1,3 @@
+# Build
+
+Documentation is not yet complete.
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,23 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Scaffold"
+  text: "Zotero Plugins"
+  tagline: The Modern Development Experience for Zotero Plugins
+  actions:
+    - theme: brand
+      text: Quick Start
+      link: /quick-start
+
+features:
+  - title: Dev Serve
+    details: Auto reload your plugin when source code changed
+  - title: Build Plugin
+    details: TypeScript supported, many utils builders
+  - title: Pack plugin
+    details: Pack code to xpi file
+  - title: Release
+    details: Auto bump version, and publish your plugin to GitHub
+---