docs: improve typedocs — clean rebase of #2563

.github/workflows/release.yaml

@@ -38,7 +38,7 @@ jobs:
         run: |
           git config --global user.name 'contentful-automation[bot]'
           git config --global user.email '${{ steps.get-user-id.outputs.user-id }}+contentful-automation[bot]@users.noreply.github.com'
-      
+
       - name: Checkout code
         uses: actions/checkout@v5
         with:
@@ -72,14 +72,6 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Publish Docs
-        if: github.event_name == 'push' && contains(fromJSON('["refs/heads/master"]'), github.ref)
-        run: |
-          echo "Publishing Documentation"
-          npm run docs:publish
-        env:
-          GITHUB_TOKEN: ${{ steps.vault.outputs.GITHUB_TOKEN }}
-
       - name: Get latest release tag
         id: get-tag
         run: |
@@ -88,10 +80,50 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ steps.vault.outputs.GITHUB_TOKEN }}
 
+      - name: Publish Docs
+        run: |
+          VERSION=$(echo "${{ steps.get-tag.outputs.tag }}" | sed 's/^v//')
+          NAMESPACE="contentful-management"
+          REPO_URL="https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git"
+          PAGES_URL="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}"
+
+          echo "Publishing docs for v${VERSION}..."
+          DOCS_BASE_URL="${PAGES_URL}/${NAMESPACE}/latest/" npm run docs:build
+
+          PAGES_DIR=$(mktemp -d)
+          git clone --single-branch --branch gh-pages "$REPO_URL" "$PAGES_DIR"
+
+          mkdir -p "$PAGES_DIR/$NAMESPACE/$VERSION"
+          cp -r ./out/* "$PAGES_DIR/$NAMESPACE/$VERSION/"
+          rm -rf "$PAGES_DIR/$NAMESPACE/latest"
+          cp -r "$PAGES_DIR/$NAMESPACE/$VERSION" "$PAGES_DIR/$NAMESPACE/latest"
+
+          # Generate versions.json from existing version directories
+          ls -d "$PAGES_DIR/$NAMESPACE"/*/ 2>/dev/null \
+            | xargs -I{} basename {} \
+            | grep -v latest \
+            | sort -rV \
+            | jq -R . | jq -s '["latest"] + .' \
+            > "$PAGES_DIR/$NAMESPACE/versions.json"
+
+          # Root redirect
+          echo "<meta http-equiv=\"refresh\" content=\"0; url=${NAMESPACE}/latest/\">" \
+            > "$PAGES_DIR/index.html"
+
+          cd "$PAGES_DIR"
+          git add .
+          git commit -m "docs: publish v${VERSION} [skip ci]" || echo "No changes to commit"
+          git push origin gh-pages
+          rm -rf "$PAGES_DIR"
+
+          echo "Docs published to ${PAGES_URL}/${NAMESPACE}/latest/"
+        env:
+          GITHUB_TOKEN: ${{ steps.vault.outputs.GITHUB_TOKEN }}
+
       - name: Summary
         run: |
           VERSION=$(echo "${{ steps.get-tag.outputs.tag }}" | sed 's/^v//')
           echo "## Release Summary" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "- **Version**: ${{ steps.get-tag.outputs.tag }}" >> $GITHUB_STEP_SUMMARY
-          echo "- **GitHub Release**: https://github.com/${{ github.repository }}/releases/tag/${{ steps.get-tag.outputs.tag }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **GitHub Release**: https://github.com/${{ github.repository }}/releases/tag/${{ steps.get-tag.outputs.tag }}" >> $GITHUB_STEP_SUMMARY

.gitignore

@@ -2,7 +2,7 @@ dist
 gh-pages
 webpack-build-log.json
 
-# Esdoc dirs
+# TypeDoc output
 out
 gh-pages
 

CONTRIBUTING.md

@@ -34,53 +34,39 @@ It also explains what to do in case you want to setup the project locally and ru
 
 # Setup
 
-This project is written in ES2015 and transpiled to ES5 using Babel, to the `dist` directory. This should generally only happen at publishing time, or for testing purposes only.
+This project is written in TypeScript. Sources live in `lib/` and are bundled to `dist/` (ESM, CJS, types, browser) using Rollup.
 
-Run `npm install` to install all necessary dependencies. When running `npm install` locally, `dist` is not compiled.
+Run `npm install` to install all necessary dependencies. All tools can be accessed via npm scripts — there is no need to install anything globally.
 
-All necessary dependencies are installed under `node_modules` and any necessary tools can be accessed via npm scripts. There is no need to install anything globally.
-
-When importing local, in development code, via `index.js`, this file checks if `dist` exists and uses that. Otherwise, it uses the code from `lib`.
-
-If you have a `dist` directory, run `npm run clean`.
-
-Axios, one of the main dependencies is vendored. This generally shouldn't matter, but if you'd like to understand why, check [SETUP.md](SETUP.md)
+If you have a `dist` directory from a previous build, run `npm run clean`.
 
 # Code style
 
-This project uses [standard](https://github.com/feross/standard). Install a relevant editor plugin if you'd like.
+This project uses ESLint and Prettier. Run `npm run lint` to check and `npm run prettier:write` to format.
 
-Everywhere where it isn't applicable, follow a style similar to the existing code.
+Follow a style similar to the existing code.
 
 # Commit messages and issues
 
 This project uses the [Angular JS Commit Message Conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit), via semantic-release. See the semantic-release [Default Commit Message Format](https://github.com/semantic-release/semantic-release#default-commit-message-format) section for more details.
 
 # Running tests
 
-This project has unit and integration tests. Both of these run on both Node.js and Browser environments.
-
-Both of these test environments are setup to deal with Babel and code transpiling, so there's no need to worry about that
+This project has unit, type, and integration tests, powered by Vitest.
 
-- `npm test` runs all three kinds of tests and generates a coverage report
-- `npm run test:unit` runs Node.js unit tests without coverage. `npm run test:cover` to run Node.js unit tests with coverage. `npm run test:debug` runs babel-node in debug mode (same as running `node debug`). In order to see an output of the tests in the terminal run `npm run test:unit-watch`.
-- `npm run test:integration` runs the integration tests against the Contentful CDA API. Note: these are tricky to run locally since they currently run against a real contentful org. Focus on unit tests during development as integration tests will be run as part of CI/CD.
-- `npm run test:browser` runs both the unit and integration tests using Karma against local browsers.
-- `npm run test:ci` runs tests in CI
-- `npm run test:browser-remote` runs both the unit and integration tests using Karma against Sauce Labs. This is only usable in the CI environment, as it expects the credentials and connection tunnel to be present.
+- `npm test` runs the full test suite (unit + types + integration + size)
+- `npx vitest --project unit --run` runs unit tests
+- `npx vitest --project types --run` runs type tests
+- `npm run test:integration` runs integration tests against the Contentful CMA API. These run against a real Contentful org, so focus on unit tests during development — integration tests run as part of CI/CD.
 
 # Documentation
 
-Code is documented using Typedoc, and reference documentation is published automatically with each new version.
+Code is documented using [TypeDoc](https://typedoc.org/), and reference documentation is published automatically to GitHub Pages with each release.
 
-- `npm run docs:watch` watches code directory, and rebuilds documentation when anything changes. Useful for documentation writing and development.
-- `npm run docs:dev` builds code and builds docs afterwards. Used by `npm run docs:watch`. Code building is required as the documentation is generated from the unminified ES5 compiled sources, rather than the original ES6 sources. You should then open the generated `out/index.html` in your browser.
-- `npm run build:docs` builds documentation.
-- `npm run docs:publish` builds documentation and publishes it to github pages.
+- `npm run docs:build` generates documentation into `out/`
+- `npm run docs:dev` builds documentation in watch mode
 
 # Other tasks
 
-- `npm run clean` removes any built files
-- `npm run build` builds vendored files, node package and browser version
-- `npm run build:dist` builds ES5 sources from ES6 ones
-- `npm run build:standalone` builds unminified and minified sources for browsers
+- `npm run clean` removes built files
+- `npm run build` builds all bundles (ESM, CJS, types, browser) via Rollup

README.md

@@ -11,12 +11,10 @@
 <h3 align="center">JavaScript</h3>
 
 <p align="center">
-  <a href="README.md">Readme</a> ·
-  <a href="SETUP.md">Setup</a> ·
-  <a href="MIGRATION.md">Migration</a> ·
-  <a href="CHANGELOG.md">Changelog</a> ·
-  <a href="CONTRIBUTING.md">Contributing</a> ·
-  <a href="SUPPORT.md">Support Policy</a>
+  <a href="README.md">Readme</a> · 
+  <a href="SETUP.md">Setup</a> · 
+  <a href="CHANGELOG.md">Changelog</a> · 
+  <a href="CONTRIBUTING.md">Contributing</a>
 </p>
 
 <p align="center">
@@ -43,20 +41,19 @@
 
 <!-- TOC -->
 
-- [Features](#features)
-- [Supported Environments](#supported-environments)
-- [Getting Started](#getting-started)
+- [Getting started](#getting-started)
   - [Installation](#installation)
-    - [Node](#node)
-    - [Browser](#browser-bundle-in-script-tag)
-    - [Typings](#typings)
+    - [Node:](#node)
+    - [Browser bundle in script tag:](#browser-bundle-in-script-tag)
+  - [Typings](#typings)
   - [Authentication](#authentication)
   - [Using ES6 import](#using-es6-import)
-  - [Your first Request](#your-first-request)
+  - [Using CommonJS require imports](#using-commonjs-require-imports)
+  - [Your first request](#your-first-request)
   - [Legacy Client Interface](#legacy-client-interface)
-- [App Framework](#app-framework)
-- [Troubleshooting](#troubleshooting)
-- [Documentation/References](#documentationreferences)
+  - [App Framework](#app-framework)
+  - [Troubleshooting](#troubleshooting)
+  - [Documentation/References](#documentationreferences)
   - [Configuration](#configuration)
   - [Reference Documentation](#reference-documentation)
   - [Contentful Javascript resources](#contentful-javascript-resources)

docs/getting-started.md

@@ -0,0 +1,34 @@
+---
+title: Getting Started
+category: Core
+---
+
+# Getting Started
+
+## Plain Client (Recommended)
+
+The plain client provides flat, Promise-based access to all CMA endpoints:
+
+```typescript
+import { createClient } from 'contentful-management'
+
+const client = createClient({ accessToken: 'YOUR_ACCESS_TOKEN' })
+
+const entries = await client.entry.getMany({
+  spaceId: '<space_id>',
+  environmentId: '<environment_id>',
+})
+```
+
+See {@link plain/plain-client-types!PlainClientAPI | PlainClientAPI} for the full API reference.
+
+## Legacy Client (Deprecated)
+
+The legacy client uses a nested, chained interface:
+
+```typescript
+const client = createClient({ accessToken: 'YOUR_ACCESS_TOKEN' }, { type: 'plain' })
+// This returns a ClientAPI instance — see createClientApi
+```
+
+See [createClientApi](../create-contentful-api/default) for the full legacy API reference.

docs/plugins/version-selector/typedoc-version-selector.mjs

@@ -0,0 +1,30 @@
+import { readFileSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { JSX } from 'typedoc'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const css = readFileSync(resolve(__dirname, 'version-selector.css'), 'utf-8')
+const js = readFileSync(resolve(__dirname, 'version-selector.js'), 'utf-8')
+
+/**
+ * TypeDoc plugin that injects a version selector dropdown at the top of the
+ * left sidebar.
+ *
+ * At runtime in the browser, the dropdown fetches `versions.json` from the docs
+ * root (generated by the CI deploy workflow) and lets users switch between
+ * published documentation versions.
+ *
+ * The CSS and JS are kept in separate files (`version-selector.css` and
+ * `version-selector.js`) for readability, and read at build time.
+ *
+ * @param {import('typedoc').Application} app
+ */
+export function load(app) {
+  app.renderer.hooks.on('head.end', () => {
+    return JSX.createElement(JSX.Fragment, null, [
+      JSX.createElement('style', null, [JSX.createElement(JSX.Raw, { html: css })]),
+      JSX.createElement('script', null, [JSX.createElement(JSX.Raw, { html: js })]),
+    ])
+  })
+}

docs/plugins/version-selector/version-selector.css

@@ -0,0 +1,47 @@
+.tsd-version-selector {
+  display: block;
+  padding: 0.5rem 0.75rem 0.75rem;
+  border-bottom: 1px solid var(--color-accent, #ccc);
+  margin-bottom: 0.5rem;
+}
+.tsd-version-selector label {
+  display: block;
+  font-size: 0.75rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--color-text-aside, #666);
+  margin-bottom: 0.25rem;
+}
+.tsd-version-selector select {
+  appearance: none;
+  -webkit-appearance: none;
+  width: 100%;
+  background: var(--color-background-secondary, #f5f5f5);
+  color: var(--color-text, #222);
+  border: 1px solid var(--color-accent, #ccc);
+  border-radius: 4px;
+  padding: 0.35rem 1.75rem 0.35rem 0.5rem;
+  font-size: 0.85rem;
+  font-family: inherit;
+  cursor: pointer;
+  line-height: 1.4;
+}
+.tsd-version-selector select:hover {
+  border-color: var(--color-ts-function, #6f42c1);
+}
+.tsd-version-selector .tsd-version-select-wrap {
+  position: relative;
+  display: block;
+}
+.tsd-version-selector .tsd-version-select-wrap::after {
+  content: '';
+  position: absolute;
+  right: 0.5rem;
+  top: 50%;
+  transform: translateY(-50%);
+  border-left: 4px solid transparent;
+  border-right: 4px solid transparent;
+  border-top: 5px solid var(--color-text, #222);
+  pointer-events: none;
+}

docs/plugins/version-selector/version-selector.js

@@ -0,0 +1,79 @@
+;(function () {
+  function initVersionSelector() {
+    // Target: top of the left sidebar (.site-menu)
+    var sidebar = document.querySelector('.site-menu')
+    if (!sidebar) return
+
+    // Determine the base path for versioned docs
+    // Expected URL structure: .../contentful-management/<VERSION>/...
+    var pathSegments = window.location.pathname.split('/')
+    var cmIdx = pathSegments.indexOf('contentful-management')
+    if (cmIdx === -1) return
+
+    var currentVersion = pathSegments[cmIdx + 1]
+    if (!currentVersion) return
+
+    var docsBase = pathSegments.slice(0, cmIdx + 1).join('/')
+    var versionsUrl = docsBase + '/versions.json'
+
+    fetch(versionsUrl)
+      .then(function (r) {
+        return r.ok ? r.json() : Promise.reject('not found')
+      })
+      .then(function (versions) {
+        if (!versions || !versions.length) return
+
+        var wrapper = document.createElement('div')
+        wrapper.className = 'tsd-version-selector'
+
+        var label = document.createElement('label')
+        label.setAttribute('for', 'tsd-version-select')
+        label.textContent = 'Version'
+        wrapper.appendChild(label)
+
+        var selectWrap = document.createElement('div')
+        selectWrap.className = 'tsd-version-select-wrap'
+
+        var select = document.createElement('select')
+        select.id = 'tsd-version-select'
+        select.setAttribute('aria-label', 'Documentation version')
+
+        versions.forEach(function (v) {
+          var opt = document.createElement('option')
+          opt.value = v
+          opt.textContent = v === 'latest' ? v : 'v' + v
+          if (v === currentVersion) opt.selected = true
+          select.appendChild(opt)
+        })
+
+        // If current version isn't in the list, add it
+        if (!versions.includes(currentVersion)) {
+          var opt = document.createElement('option')
+          opt.value = currentVersion
+          opt.textContent = currentVersion === 'latest' ? currentVersion : 'v' + currentVersion
+          opt.selected = true
+          select.insertBefore(opt, select.firstChild)
+        }
+
+        select.addEventListener('change', function () {
+          var newVersion = select.value
+          var subPath = pathSegments.slice(cmIdx + 2).join('/')
+          var newUrl = docsBase + '/' + newVersion + '/' + subPath
+          window.location.href = newUrl
+        })
+
+        selectWrap.appendChild(select)
+        wrapper.appendChild(selectWrap)
+        sidebar.insertBefore(wrapper, sidebar.firstChild)
+      })
+      .catch(function () {
+        // versions.json not available — skip selector (e.g. local dev)
+      })
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initVersionSelector)
+  } else {
+    initVersionSelector()
+  }
+})()