docs: tweaks

Author: northword

.devcontainer/devcontainer.json

@@ -3,16 +3,28 @@
 {
   "name": "Zotero Plugins Marketplace",
   // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
-  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm",
+  // https://github.com/devcontainers/images/tree/main/src/base-ubuntu
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
 
   // Features to add to the dev container. More info: https://containers.dev/features.
   "features": {
-    "ghcr.io/devcontainers-contrib/features/pnpm:2": {}
+    // https://github.com/devcontainers/features/blob/main/src/node/README.md
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "lts",
+      "pnpmVersion": "latest"
+    }
   },
 
   // Use 'forwardPorts' to make a list of ports inside the container available locally.
-  // "forwardPorts": [5173, 4173],
-  // "portsAttributes": {},
+  "forwardPorts": [5173, 4173],
+  "portsAttributes": {
+    "5173": {
+      "label": "dev port"
+    },
+    "4173": {
+      "label": "build port"
+    }
+  },
 
   // Use 'postCreateCommand' to run commands after the container is created.
   "postCreateCommand": "pnpm i",

README.md

@@ -1,73 +1,83 @@
 # Zotero Plugin Registry
 
-> A self-hosted registry and store for Zotero plugins based on their `update.json` manifests.
+**Zotero Plugin Registry** is a self-hosted, structured registry that aggregates plugin metadata by collecting and parsing developers' self-hosted `update.json` files.
 
-## Overview
+This project is the successor to the plugin listing functionality in [`zotero-chinese/zotero-plugins`](https://github.com/zotero-chinese/zotero-plugins), which was primarily designed to cache and mirror `.xpi` files hosted on GitHub to support users in mainland China. However, that system did not automatically parse plugin versions or compatibility information from `update.json`, nor did it support plugins hosted outside GitHub.
 
-Zotero Plugin Registry is a self-hosted platform that aggregates Zotero plugins by collecting developers' self-hosted `update.json` files.  
-It provides a unified service for users to browse, search, and get version and compatibility information about Zotero plugins.
+In contrast, this new repository:
+
+- Collects only essential metadata for each plugin (`meta.json`) and the URL to its `update.json`
+- Automatically fetches and parses version and compatibility info from the `update.json`
+- Generates structured JSON outputs for frontend applications or indexing
+- Serves as the canonical data source for a new, internationalized Zotero plugin store frontend
+
+The previous [frontend site](https://github.com/zotero-chinese/website) and [zotero-plugins project](https://github.com/zotero-chinese/zptero-plugins) created by the Zotero Chinese community will continue to serve Chinese users with a localized interface and GitHub mirror links. This project aims to power a new global plugin ecosystem, with improved automation, wider plugin support, and international accessibility.
 
 ## Project Structure
 
 ```plain
-main/
+.
 └── plugins/
-└── <plugin-id>/
-  ├── meta.json # Base plugin metadata (manually maintained)
-  ├── meta.generated.json # Generated metadata including versions
-  ├── latest.json # Generated latest version info
-  └── icon.png # Optional plugin icon
+   └── <plugin-id>/
+      ├── meta.json            # Base plugin metadata (manually maintained)
+      ├── meta.generated.json  # Generated metadata including versions
+      └── icon.png             # Optional plugin icon
 scripts/
-└── build.ts # Build script to generate aggregated data
-.gitignore # Ignore generated JSON files
-package.json # Project config and dependencies
-README.md # This document
+└── build.ts                   # Build script to generate aggregated data
+package.json                   # Project config and dependencies
+README.md                      # This document
 ```
 
-## Quick Start
-
-1. Clone the repository and install dependencies
-
-   ```bash
-   git clone https://github.com/zotero-plugin-dev/zotero-plugin-registry.git
-   cd zotero-plugin-registry
-   pnpm install
-   ```
-
-2. Add plugin metadata in `main/plugins/<plugin-id>/meta.json`, example:
-
-   ```json
-   {
-     "id": "[email protected]",
-     "name": "Zotero Format Metadata",
-     "update_json": "https://example.com/path/to/update.json",
-     "description": "A useful Zotero plugin.",
-     "homepage": "https://github.com/northword/zotero-format-metadata",
-     "tags": ["metadata"]
-   }
-   ```
-
-3. Run the build script to generate aggregated data
+## Submitting Plugins
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/zotero-plugin-dev/zotero-plugin-registry?quickstart=1)
+
+> [!NOTE]
+>
+> How to add a plugin that hasn't been included?
+>
+> Add plugin metadata in `./plugins/<plugin-id>/meta.json`, the basic format is shown below, and existing items can also be used as references.
+>
+> After editing, commit and pull request. We will process it as soon as possible.
+
+```json
+{
+  "id": "[email protected]",
+  "name": "Zotero Format Metadata",
+  "update_json": "https://example.com/path/to/update.json",
+  "description": "A useful Zotero plugin.",
+  "homepage": "https://github.com/northword/zotero-format-metadata",
+  "tags": ["metadata"]
+}
+```
 
-   ```bash
-   pnpm run build
-   ```
+## Development Guide
 
-4. After building, `meta.generated.json` and `latest.json` files will be created inside each plugin directory, ready for deployment or frontend consumption.
+Before starting development, you need to create a [GitHub personal access token](https://docs.github.com/zh/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) and store it in the local environment variable `GITHUB_TOKEN`.
 
-## Build Script Usage
+```bash
+# Clone the repository
+git clone https://github.com/zotero-plugin-dev/zotero-plugin-registry.git
+cd zotero-plugin-registry
 
-- Build all plugins:
+# Install dependencies
+corepack enable
+pnpm install
 
-```bash
+# Build all plugins:
 pnpm run build
+
+# Build a specific plugin by ID:
+pnpm run --only [email protected]
 ```
 
-- Build a specific plugin by ID:
+After script run, `meta.generated.json` and `latest.json` files will be created inside each plugin directory, ready for deployment or frontend consumption.
 
-```bash
-pnpx ts-node scripts/build.ts --only [email protected]
-```
+> [!NOTE]
+>
+> How to use this project as a dependency for secondary development?
+>
+> Developers can use the dist files like `index.json` from the `publish` branch.
 
 ## Contributing