Skip to content

Commit c57f634

Browse files
sneakers-the-ratnorthword
sneakers-the-rat
and
northword
authored
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]>
1 parent 9266dea commit c57f634

14 files changed

Lines changed: 1690 additions & 179 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
name: docs
2+
3+
on:
4+
# Runs on pushes targeting the `main` branch. Change this to `master` if you're
5+
# using the `master` branch as the default branch.
6+
push:
7+
branches: [main]
8+
9+
# Allows you to run this workflow manually from the Actions tab
10+
workflow_dispatch:
11+
12+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
13+
permissions:
14+
contents: read
15+
pages: write
16+
id-token: write
17+
18+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
19+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
20+
concurrency:
21+
group: pages
22+
cancel-in-progress: false
23+
24+
jobs:
25+
# Build job
26+
build:
27+
runs-on: ubuntu-latest
28+
steps:
29+
- name: Checkout
30+
uses: actions/checkout@v4
31+
with:
32+
fetch-depth: 0 # Not needed if lastUpdated is not enabled
33+
34+
- name: Setup pnpm
35+
uses: pnpm/action-setup@v4
36+
37+
- name: Setup Node.js
38+
uses: actions/setup-node@v4
39+
with:
40+
node-version: 20
41+
cache: pnpm
42+
43+
- name: Setup Pages
44+
uses: actions/configure-pages@v4
45+
46+
- name: Install dependencies
47+
run: pnpm install
48+
49+
- name: Build with VitePress
50+
run: pnpm docs:build
51+
52+
- name: Upload artifact
53+
uses: actions/upload-pages-artifact@v3
54+
with:
55+
path: docs/.vitepress/dist
56+
57+
# Deployment job
58+
deploy:
59+
environment:
60+
name: github-pages
61+
url: ${{ steps.deployment.outputs.page_url }}
62+
needs: build
63+
runs-on: ubuntu-latest
64+
name: Deploy
65+
steps:
66+
- name: Deploy to GitHub Pages
67+
id: deployment
68+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,8 @@ node_modules
55

66
dist
77
build
8-
.npmrc
8+
.npmrc
9+
10+
# vitepress
11+
docs/.vitepress/dist
12+
docs/.vitepress/cache

‎README.md‎

Lines changed: 2 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -14,132 +14,9 @@ This project is under active development, and some APIs may change. However, it
1414

1515
For best practices regarding this package, please refer to [zotero-plugin-template](https://github.com/windingwind/zotero-plugin-template).
1616

17-
## Using in a blank project
17+
## Documentation
1818

19-
<details>
20-
21-
<summary>WIP: Not yet implemented</summary>
22-
23-
```bash
24-
# npm
25-
npx zotero-plugin create
26-
# pnpm
27-
pnpm dlx zotero-plugin create
28-
```
29-
30-
</details>
31-
32-
## Using in an existing project
33-
34-
### 01. Install
35-
36-
#### From NPM
37-
38-
```bash
39-
npm install -D zotero-plugin-scaffold
40-
41-
yarn add -D zotero-plugin-scaffold
42-
43-
pnpm add -D zotero-plugin-scaffold
44-
```
45-
46-
#### From source code
47-
48-
```bash
49-
# clone this repo
50-
git clone https://github.com/northword/zotero-plugin-scaffold.git zotero-plugin-scaffold/
51-
cd zotero-plugin-scaffold/
52-
53-
# build
54-
pnpm install
55-
pnpm build # or pnpm dev
56-
57-
# npm link
58-
cd your-plugin-work-dir/
59-
pnpm link ../zotero-plugin-scaffold
60-
```
61-
62-
### 02. Create a config file
63-
64-
The configuration file needs to be stored in the following location.
65-
66-
```bash
67-
zotero-plugin.config.ts # also avaliable in *.js *.mjs *.cjs *.ts
68-
```
69-
70-
You can import helper `defineConfig` to get type hints. If no value is specified for an optional property, the default value will be used.
71-
72-
```ts
73-
import { defineConfig } from "zotero-plugin-scaffold";
74-
75-
export default defineConfig({
76-
name: "the plugin name",
77-
id: "the plugin id",
78-
namespace: "the plugin namespace",
79-
build: {
80-
esbuildOptions: [
81-
{
82-
entryPoints: ["src/index.ts"],
83-
bundle: true,
84-
target: "firefox115",
85-
},
86-
],
87-
},
88-
});
89-
```
90-
91-
Full config please refrence in [src/types](./src/types/index.ts).
92-
93-
### 03. Create a env file
94-
95-
This file defines Zotero's runtime configuration such as binary paths, profile paths, and environment variables required for Node scripts to run.
96-
97-
NOTE: Do not check-in this file to the repository!
98-
99-
```bash
100-
.env
101-
```
102-
103-
```ini
104-
# The path of the Zotero binary file.
105-
# The path is `*/Zotero.app/Contents/MacOS/zotero` for macOS.
106-
ZOTERO_PLUGIN_ZOTERO_BIN_PATH = /path/to/zotero.exe
107-
108-
# The path of the profile used for development.
109-
# Start the profile manager by `/path/to/zotero.exe -p` to create a profile for development.
110-
# @see https://www.zotero.org/support/kb/profile_directory
111-
ZOTERO_PLUGIN_PROFILE_PATH = /path/to/profile
112-
```
113-
114-
### 04. Add scripts to package.json
115-
116-
```json
117-
{
118-
"scripts": {
119-
"start": "zotero-plugin serve",
120-
"build": "zotero-plugin build",
121-
"release": "zotero-plugin release"
122-
}
123-
}
124-
```
125-
126-
### 05. Run
127-
128-
```bash
129-
pnpm run start
130-
pnpm run build
131-
```
132-
133-
## Using in NodeJS code
134-
135-
```ts
136-
import { Build, Config } from "zotero-plugin-scaffold";
137-
138-
const config = await Config.loadConfig();
139-
140-
const Builder = new Build(config);
141-
await Builder.run();
142-
```
19+
[Read the Docs to Learn More.](https://northword.github.io/zotero-plugin-scaffold)
14320

14421
## Contributing
14522

‎docs/.vitepress/.gitkeep‎

Whitespace-only changes.

‎docs/.vitepress/config.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
import { defineConfig } from "vitepress";
2+
3+
// https://vitepress.dev/reference/site-config
4+
export default defineConfig({
5+
title: "Zotero Plugin Scaffold",
6+
description: "Delivering a Modern and Elegant Development Experience for Zotero Plugins.",
7+
base: "/zotero-plugin-scaffold/",
8+
themeConfig: {
9+
// https://vitepress.dev/reference/default-theme-config
10+
nav: [
11+
{ text: "Home", link: "/" },
12+
],
13+
14+
sidebar: [
15+
{ text: "Why", link: "/why" },
16+
{ text: "Quick Start", link: "/quick-start" },
17+
{ text: "Serve", link: "/serve" },
18+
{ text: "Build", link: "/build" },
19+
{ text: "Test", link: "/test" },
20+
{ text: "Release", link: "/release" },
21+
],
22+
23+
socialLinks: [
24+
{ icon: "github", link: "https://github.com/northword/zotero-plugin-scaffold" },
25+
],
26+
},
27+
});

‎docs/build.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Build
2+
3+
Documentation is not yet complete.

‎docs/index.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
# https://vitepress.dev/reference/default-theme-home-page
3+
layout: home
4+
5+
hero:
6+
name: "Scaffold"
7+
text: "Zotero Plugins"
8+
tagline: The Modern Development Experience for Zotero Plugins
9+
actions:
10+
- theme: brand
11+
text: Quick Start
12+
link: /quick-start
13+
14+
features:
15+
- title: Dev Serve
16+
details: Auto reload your plugin when source code changed
17+
- title: Build Plugin
18+
details: TypeScript supported, many utils builders
19+
- title: Pack plugin
20+
details: Pack code to xpi file
21+
- title: Release
22+
details: Auto bump version, and publish your plugin to GitHub
23+
---

0 commit comments

Comments
 (0)