chore: Ci/GitHub actions

.devcontainer/devcontainer.json

@@ -0,0 +1,26 @@
+{
+  "name": "docusaurus-plugin-gitlab",
+
+  // Image ships with nvm preinstalled (default Node 20). We additionally install
+  // the other CI matrix versions so you can switch instantly, e.g. `nvm use 18`.
+  "image": "mcr.microsoft.com/devcontainers/javascript-node:20-bookworm",
+
+  // Install the full CI matrix (20 / 22 / 24) and keep 20 (the minimum) as default.
+  "onCreateCommand": "bash -c 'export NVM_DIR=/usr/local/share/nvm && . \"$NVM_DIR/nvm.sh\" && nvm install 20 && nvm install 22 && nvm install 24 && nvm alias default 20'",
+
+  // Install dependencies once the container is up.
+  "postCreateCommand": "npm ci",
+
+  // Docusaurus dev server (used by the example sites) listens here.
+  "forwardPorts": [3000],
+
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "dbaeumer.vscode-eslint",
+        "DavidAnson.vscode-markdownlint",
+        "vitest.explorer"
+      ]
+    }
+  }
+}

.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions: {}
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [20, 22, 24]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+          cache-dependency-path: |
+            package-lock.json
+            examples/site/package-lock.json
+      - run: npm ci
+      - name: "Build package (needed by the example site file: link)"
+        run: npm run build
+      - name: Install example site deps
+        working-directory: examples/site
+        run: npm ci
+      - name: Run tests (unit + e2e docusaurus build)
+        run: npm test
+
+  dependency-review:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/dependency-review-action@2031cfc080254a8a887f58cffee85186f0e49e48 # v4.9.0
+        with:
+          fail-on-severity: high

.github/workflows/codeql.yml

@@ -0,0 +1,27 @@
+name: CodeQL
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  schedule:
+    - cron: "27 3 * * 1"
+
+permissions: {}
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+      actions: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: github/codeql-action/init@dd903d2e4f5405488e5ef1422510ee31c8b32357 # v3.36.2
+        with:
+          languages: javascript-typescript
+      - uses: github/codeql-action/analyze@dd903d2e4f5405488e5ef1422510ee31c8b32357 # v3.36.2
+        with:
+          category: "/language:javascript-typescript"

.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions: {}
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - id: release
+        uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071 # v4.4.1
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+          cache: npm
+      - name: Use OIDC-capable npm
+        run: npm install -g npm@latest
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish --provenance --access public

.github/workflows/scorecard.yml

@@ -0,0 +1,29 @@
+name: Scorecard
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "18 4 * * 1"
+
+permissions: {}
+
+jobs:
+  analysis:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+      - uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+      - uses: github/codeql-action/upload-sarif@dd903d2e4f5405488e5ef1422510ee31c8b32357 # v3.36.2
+        with:
+          sarif_file: results.sarif

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

CLAUDE.md

@@ -13,9 +13,12 @@ static HTML. The browser never holds a token or calls the GitLab API.
 
 ## Hard rules
 
-- **DO NOT use git.** Never run any git command (no `init`, `status`, `add`,
-  `commit`, anything). This repo is intentionally not a git repository.
-- **Docusaurus 3 only** (MDX v3, unified ESM, Node 18+ `fetch`).
+- **Git/GitHub:** This is a live GitHub repo (`ebuildy/docusaurus-plugin-gitlab`).
+  Normal git usage is fine. CI runs on PRs and pushes to `main` via GitHub
+  Actions (`.github/workflows/`); releases are automated with release-please and
+  published to npm via OIDC trusted publishing — see CONTRIBUTING.md.
+- **Docusaurus 3 only** (MDX v3, unified ESM, native `fetch`). **Node 20, 22, 24**
+  (Docusaurus 3 requires Node 20+; the e2e build will not run on Node 18).
 - Prefer the latest versions of libraries.
 - ESM-first. Intra-package imports use explicit `.js` extensions
   (e.g. `import { Fallback } from "./Fallback.js"`) — required by the
@@ -25,7 +28,12 @@ static HTML. The browser never holds a token or calls the GitLab API.
 
 ## Commands
 
-- `npm run build` — build the package with tsup (ESM + CJS + d.ts) into `dist/`.
+- `npm run build` — build the package with tsup (ESM + d.ts) into `dist/`.
+  The package is **ESM-only**: every remark/rehype/unified dependency is pure ESM,
+  so a CJS build would `require()` them — which breaks under Node's `require(ESM)`
+  interop (`unified().use()` receives `{ default: fn }` → "empty preset", failing
+  the Docusaurus build). Do not re-add a `cjs` tsup format or a `require` export
+  condition; `test/packaging.test.ts` guards this.
 - `npm run test` — run all tests (Vitest). Use `npx vitest run <file>` for one file.
 - `npm run typecheck` — `tsc --noEmit`.
 

CONTRIBUTING.md

@@ -5,8 +5,10 @@ you from clone to a green build.
 
 ## Prerequisites
 
-- **Node 18+** and **npm**
+- **Node 20, 22, or 24** and **npm** (Docusaurus 3 requires Node 20+)
 - A GitLab token is **not** required for development (the tests mock the API).
+- Optionally, a **Dev Container** (`.devcontainer/`) — open the repo in a container
+  with nvm preloaded with Node 20/22/24; switch with `nvm use 22`.
 
 ## Setup
 
@@ -27,7 +29,7 @@ npm run build      # bundle the package into dist/
 | `npm run typecheck` | `tsc --noEmit` |
 | `npm run lint` | ESLint + markdownlint |
 | `npm run lint:fix` | Auto-fix lint issues |
-| `npm run build` | Build with tsup (ESM + CJS + types) |
+| `npm run build` | Build with tsup (ESM-only + types) |
 
 The example sites have their own READMEs:
 [`examples/site`](./examples/site/README.md) (mocked, drives the e2e) and
@@ -61,6 +63,31 @@ npm run lint && npm run typecheck && npm test
 
 Keep changes focused, and add/adjust tests for any behavior you change.
 
+## Releasing
+
+Releases are automated with [release-please](https://github.com/googleapis/release-please)
+and published to npm with provenance via OIDC trusted publishing.
+
+1. Land changes on `main` using **conventional commits** (`feat:`, `fix:`,
+   `chore:`, …). `feat:` bumps the minor version, `fix:` the patch version.
+2. release-please opens/maintains a **release PR** (`chore: release x.y.z`) that
+   bumps `package.json` + `.release-please-manifest.json` and updates the
+   changelog.
+3. Merge the release PR. The `Release` workflow tags the release and the
+   `publish` job runs `npm publish --provenance --access public`. No npm token is
+   stored — publishing authenticates via GitHub OIDC.
+
+### One-time setup
+
+- On npmjs.com, add `ebuildy/docusaurus-plugin-gitlab` +
+  `.github/workflows/release.yml` as a **trusted publisher** for
+  `@ebuildy/docusaurus-plugin-gitlab`.
+- **First publish only:** because the package name does not yet exist on npm, the
+  very first publish may need to be bootstrapped manually from a clean checkout:
+  `npm ci && npm run build && npm publish --access public` (without
+  `--provenance`, which requires CI/OIDC). Subsequent releases publish
+  automatically.
+
 ## Working with AI (Claude Code)
 
 This repo is set up to be worked on with **[Claude Code](https://claude.com/claude-code)**,

README.md

@@ -13,14 +13,23 @@ tokens or network calls ever reach the browser, and pages stay fast.
 - ✅ README images **and badges are downloaded and localized** (offline-safe, frozen at build time)
 - ✅ On-disk caching, theme-aware (Infima) styling, graceful error fallbacks
 
-> Requires Docusaurus **3.x** and Node **18+**.
+> Requires Docusaurus **3.x** and Node **20, 22, or 24** (Docusaurus 3 itself
+> needs Node 20+).
 
 ## Installation
 
 ```bash
 npm install @ebuildy/docusaurus-plugin-gitlab
 ```
 
+> **ESM-only.** This package ships as ES modules (all of its remark/rehype
+> dependencies are ESM). Load it from an ESM config — `docusaurus.config.ts` or
+> `docusaurus.config.mjs` (the examples below use `import`). If your site still
+> uses a CommonJS `docusaurus.config.js` on **Node < 20.19**, either switch the
+> config to ESM or load the plugin with `await import(...)`. On **Node 20.19+**
+> (and 22+) CommonJS configs work too, since Node can `require()` ES modules
+> natively.
+
 ## Setup
 
 Two one-time steps in your Docusaurus site.
@@ -189,7 +198,7 @@ components, so you can wrap or restyle them as needed.
 
 ```bash
 npm install
-npm run build       # bundle with tsup (ESM + CJS + types)
+npm run build       # bundle with tsup (ESM-only + types)
 npm run test        # unit tests (Vitest)
 npm run typecheck   # tsc --noEmit
 ```