Skip to content

feat: unify docs#10649

Merged
jasonsaayman merged 15 commits intov1.xfrom
feat/unify-docs
Apr 4, 2026
Merged

feat: unify docs#10649
jasonsaayman merged 15 commits intov1.xfrom
feat/unify-docs

Conversation

@jasonsaayman
Copy link
Copy Markdown
Member

@jasonsaayman jasonsaayman commented Apr 4, 2026

Summary by cubic

Unifies all project docs into a single vitepress site under docs/, hardens CI by installing with --ignore-scripts, and bumps esbuild in the docs build to a safe version. Also fixes docs errors and minor styling issues for a cleaner launch.

Description

  • Summary of changes
    • Added a vitepress docs site in docs/ with custom theme, home, API, guides, examples, and sponsors pages.
    • Introduced sponsors data and processing script; patched @splidejs/splide to ESM for the docs UI.
    • Expanded SECURITY.md with clearer reporting and disclosure steps.
    • CI: switched installs to npm ci --ignore-scripts; smoke tests use npm install --ignore-scripts.
    • Root package.json: added docs:dev; .gitignore: now tracks docs/ and ignores docs/.vitepress/{dist,cache}.
    • Docs package.json: added overrides to bump esbuild to ^0.25.0 to mitigate risk.
    • Fixed content inconsistencies and typos; cleaned up wording and card styles.
  • Reasoning
    • Centralize guidance in one modern site; isolate docs deps.
    • Reduce CI supply‑chain risk by disabling lifecycle scripts; address esbuild security concerns.
    • Clarify security reporting to speed triage.
  • Additional context
    • Docs live under docs/ with their own package.json (type: module).
    • Sponsors are built via docs/scripts/process-sponsors.js and included in builds.
    • The docs bundle includes axios only for examples; it’s scoped to the docs package.
    • One remaining slug to normalize: type-script.md.

Docs

  • Local dev: run npm run docs:dev (from root) or cd docs && npm run docs:dev.
  • Build for preview: cd docs && npm run prod:build (updates sponsors, then vitepress build).
  • Key files: docs/.vitepress/config.mts, docs/.vitepress/theme/, content under docs/pages/**, home at docs/index.md.

Testing

  • No unit/e2e tests added; changes are docs + CI.
  • CI now uses --ignore-scripts in publish, release-branch, run-ci, and sponsor update workflows; smoke tests install with the same flag. Verify pipelines run green.
  • Manual checks:
    • npm run docs:dev loads routes without 404s.
    • cd docs && npm run prod:build completes and renders key pages (Guide, API, Sponsors).
    • Confirm the docs build uses the esbuild override and recent typo/style fixes; verify nav slugs and links are consistent.

Written for commit aa1061d. Summary will update on new commits.

@jasonsaayman jasonsaayman self-assigned this Apr 4, 2026
@jasonsaayman jasonsaayman added priority::medium A medium priority commit::docs The PR is related to docs labels Apr 4, 2026
@socket-security
Copy link
Copy Markdown

socket-security bot commented Apr 4, 2026

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Added@​splidejs/​splide@​4.1.410010010080100
Addedpatch-package@​8.0.19710010081100
Addedvitepress@​1.6.4981008493100
Addeddayjs@​1.11.2010010010088100
Addedaxios@​1.14.09110010095100
Addedvue@​3.5.321001009197100

View full report

Copy link
Copy Markdown
Contributor

@cubic-dev-ai cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

40 issues found across 78 files

Confidence score: 3/5

  • There is a concrete runtime risk in docs/scripts/process-sponsors.js: pushing into an uninitialized tier array can crash active-sponsor reconciliation when a tier exists only in active data.
  • docs/pages/advanced/retry.md documents a Retry-After parser that ignores HTTP-date values, which can cause immediate or incorrect retries in copied implementations (clear user-impacting behavior).
  • Several docs examples are currently broken or misleading (docs/pages/advanced/testing.md, docs/pages/advanced/multipart-form-data-format.md, docs/pages/advanced/request-method-aliases.md, docs/pages/advanced/html-form-processing.md), so this is more than housekeeping even though it is mostly docs-scoped.
  • Pay close attention to docs/scripts/process-sponsors.js and docs/pages/advanced/retry.md - one can crash reconciliation logic, and the other can produce incorrect retry timing behavior.

Note: This PR contains a large number of files. cubic only reviews up to 75 files per PR, so some files may not have been reviewed.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/scripts/process-sponsors.js">

<violation number="1" location="docs/scripts/process-sponsors.js:256">
P1: Initialize the tier array before pushing in the active-sponsor reconciliation loop to avoid runtime crashes when a tier exists only in active data.</violation>
</file>

<file name="docs/pages/advanced/testing.md">

<violation number="1" location="docs/pages/advanced/testing.md:70">
P2: This example uses `axios.get.mockRejectedValueOnce(...)` without first mocking axios, so the snippet will fail when run.</violation>
</file>

<file name="docs/pages/advanced/multipart-form-data-format.md">

<violation number="1" location="docs/pages/advanced/multipart-form-data-format.md:20">
P2: The Node.js multipart example uses `fs.createReadStream` without importing `fs`, so the sample fails at runtime.</violation>

<violation number="2" location="docs/pages/advanced/multipart-form-data-format.md:49">
P2: `FormData` is required but never used in this example, so the snippet doesn’t actually show how to set `env.FormData` as described.</violation>
</file>

<file name="docs/pages/advanced/retry.md">

<violation number="1" location="docs/pages/advanced/retry.md:91">
P1: The `Retry-After` parser only handles numeric seconds and breaks when the header is an HTTP-date. Parse both formats to avoid immediate/incorrect retries.</violation>

<violation number="2" location="docs/pages/advanced/retry.md:115">
P2: The docs claim `AbortController` cancels pending retry delay, but the shown delay logic is not abort-aware. This is misleading and can cause delayed cancellation behavior.</violation>
</file>

<file name="docs/pages/misc/sponsors.md">

<violation number="1" location="docs/pages/misc/sponsors.md:29">
P2: Add `rel="noopener noreferrer"` to `_blank` external links to prevent reverse-tabnabbing.</violation>
</file>

<file name="docs/pages/advanced/request-method-aliases.md">

<violation number="1" location="docs/pages/advanced/request-method-aliases.md:24">
P2: The alias method signatures document a synchronous `AxiosResponse` return type, but axios methods return a `Promise`. This will mislead users and produce incorrect TypeScript usage examples.</violation>
</file>

<file name="docs/.vitepress/cache/deps/@splidejs_splide.js">

<violation number="1" location="docs/.vitepress/cache/deps/@splidejs_splide.js:1">
P2: Do not commit VitePress cache/bundled dependency files; this generated artifact should be removed from version control.</violation>
</file>

<file name="docs/pages/advanced/html-form-processing.md">

<violation number="1" location="docs/pages/advanced/html-form-processing.md:29">
P2: The selector in the examples does not match the form id in the HTML sample, so the documented example won’t work as written.</violation>

<violation number="2" location="docs/pages/advanced/html-form-processing.md:53">
P2: The JSON output example uses the `prop` key twice in the same object, making the documented payload ambiguous and misleading.</violation>
</file>

<file name="docs/pages/advanced/request-config.md">

<violation number="1" location="docs/pages/advanced/request-config.md:180">
P2: Missing comma after `hostname` makes the proxy example invalid JavaScript.</violation>

<violation number="2" location="docs/pages/advanced/request-config.md:267">
P2: The example object declares `data` twice, so the first `data` value is overwritten and the snippet is misleading for copy/paste use.</violation>

<violation number="3" location="docs/pages/advanced/request-config.md:273">
P2: The example object declares `adapter` twice, causing the earlier adapter function to be overwritten.</violation>
</file>

<file name="docs/pages/advanced/authentication.md">

<violation number="1" location="docs/pages/advanced/authentication.md:103">
P2: The refresh request uses a relative URL on the global axios client, so it can call the wrong origin instead of the configured API base URL.</violation>
</file>

<file name="docs/package.json">

<violation number="1" location="docs/package.json:2">
P2: Mark the docs package as private to prevent accidental publishing conflicts with the main `axios` package metadata.</violation>
</file>

<file name="docs/scripts/utils.js">

<violation number="1" location="docs/scripts/utils.js:12">
P2: Use `console.error` for error messages so they are emitted to stderr instead of stdout.</violation>
</file>

<file name="docs/pages/getting-started/features.md">

<violation number="1" location="docs/pages/getting-started/features.md:17">
P2: The browser support statement is inaccurate: it claims IE11 support, while project docs only advertise latest modern browsers.</violation>

<violation number="2" location="docs/pages/getting-started/features.md:21">
P2: This overstates Node.js test coverage: current CI tests start at Node 12, not Node 10.</violation>
</file>

<file name="docs/pages/advanced/header-methods.md">

<violation number="1" location="docs/pages/advanced/header-methods.md:35">
P2: The documented `set` signature uses `Axios` as the value type, but the API accepts `AxiosHeaderValue`.</violation>

<violation number="2" location="docs/pages/advanced/header-methods.md:36">
P2: The `rewrite` callback overload documents a `headers` argument that Axios does not provide.</violation>

<violation number="3" location="docs/pages/advanced/header-methods.md:53">
P2: `get` is documented with `AxiosHeaderMatcher`, but the API type is `AxiosHeaderParser`.</violation>
</file>

<file name="docs/pages/advanced/api-reference.md">

<violation number="1" location="docs/pages/advanced/api-reference.md:242">
P2: The `toFormData` example uses `axios.post(...)` without importing the default `axios` export.</violation>
</file>

<file name="docs/pages/advanced/fetch-adaptor.md">

<violation number="1" location="docs/pages/advanced/fetch-adaptor.md:28">
P2: The Basic example uses `axios` without importing it, so the snippet is not executable as written.</violation>

<violation number="2" location="docs/pages/advanced/fetch-adaptor.md:69">
P2: The SvelteKit example calls `axios.get` without importing `axios`, which makes the example fail at runtime.</violation>
</file>

<file name="docs/pages/advanced/type-script.md">

<violation number="1" location="docs/pages/advanced/type-script.md:7">
P2: The `moduleResolution` value is written as `"node 16"` here, but elsewhere in the same page it is `"node16"`. Use `"node16"` consistently to avoid misleading TypeScript config guidance.</violation>
</file>

<file name="docs/pages/advanced/adapters.md">

<violation number="1" location="docs/pages/advanced/adapters.md:13">
P2: This code sample redeclares `const instance` multiple times in one scope, so the snippet is not valid JavaScript when copied as a whole.</violation>
</file>

<file name="docs/pages/advanced/progress-caputing.md">

<violation number="1" location="docs/pages/advanced/progress-caputing.md:1">
P2: This new page duplicates an existing documentation page under a misspelled filename, creating redundant/orphaned docs content.</violation>
</file>

<file name="docs/pages/advanced/file-posting.md">

<violation number="1" location="docs/pages/advanced/file-posting.md:3">
P2: The statement says file uploads are always multipart, but Axios also supports sending raw file/buffer/stream bodies without multipart encoding. This should be scoped to multipart-specific APIs (e.g., `postForm`/`FormData`).</violation>

<violation number="2" location="docs/pages/advanced/file-posting.md:47">
P3: Guard `progressEvent.total` before dividing; `total` can be undefined on Axios progress events.</violation>
</file>

<file name="docs/data/sponsors.json">

<violation number="1" location="docs/data/sponsors.json:2">
P2: Duplicate sponsor records are present in the added JSON data; deduplicate repeated entries with the same slug/tier to avoid repeated rendering and inconsistent counts.</violation>
</file>

<file name="docs/pages/misc/release-cycle.md">

<violation number="1" location="docs/pages/misc/release-cycle.md:27">
P3: This sentence has grammar errors (`a auto-build`, `on through NPM`) that make the release process description unclear.</violation>

<violation number="2" location="docs/pages/misc/release-cycle.md:55">
P2: This support-policy line is already outdated at merge time and uses future tense for a past date, which makes the release policy inaccurate.</violation>
</file>

<file name="docs/pages/advanced/rate-limiting.md">

<violation number="1" location="docs/pages/advanced/rate-limiting.md:7">
P2: This description is inaccurate: `maxRate` is not limited to only two-element arrays, and the docs themselves use a one-element array (`[uploadRate]`) for upload-only limiting.</violation>
</file>

<file name="docs/pages/advanced/x-www-form-urlencoded-format.md">

<violation number="1" location="docs/pages/advanced/x-www-form-urlencoded-format.md:37">
P2: The example output includes `arr3[]`, but `arr3` is missing from the input payload, so the serialization example is inconsistent.</violation>

<violation number="2" location="docs/pages/advanced/x-www-form-urlencoded-format.md:60">
P3: The serialized output changes `surname` from `"Griffin"` to `"griffin"` without explanation, which makes the example inaccurate.</violation>
</file>

<file name="docs/pages/getting-started/upgrade-guide.md">

<violation number="1" location="docs/pages/getting-started/upgrade-guide.md:18">
P2: The interceptor migration explanation names the wrong type (`AxiosRequestConfig`), which contradicts the code example and other docs. This can mislead users during TypeScript upgrades.</violation>
</file>

<file name="docs/pages/advanced/interceptors.md">

<violation number="1" location="docs/pages/advanced/interceptors.md:47">
P3: The example redeclares `const myInterceptor` in the same scope, which makes the snippet invalid JavaScript when copied.</violation>
</file>

<file name="docs/pages/advanced/fetch-adapter.md">

<violation number="1" location="docs/pages/advanced/fetch-adapter.md:37">
P3: The inline comment on `Request: null` is incorrect and conflicts with the documented `null` behavior, which can confuse readers.</violation>
</file>

<file name="docs/pages/advanced/headers.md">

<violation number="1" location="docs/pages/advanced/headers.md:3">
P3: Use the possessive pronoun `its` instead of `it's` in the opening sentence.</violation>
</file>

Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.

Comment thread docs/scripts/process-sponsors.js
Comment thread docs/pages/advanced/retry.md
Comment thread docs/pages/advanced/testing.md
Comment thread docs/pages/advanced/multipart-form-data-format.md
Comment thread docs/pages/misc/sponsors.md Outdated
Comment thread docs/pages/advanced/file-posting.md
Comment thread docs/pages/advanced/fetch-adapter.md Outdated
Comment thread docs/pages/advanced/x-www-form-urlencoded-format.md Outdated
Comment thread docs/pages/misc/release-cycle.md Outdated
Comment thread docs/pages/advanced/headers.md Outdated
@jasonsaayman jasonsaayman merged commit 054c1f3 into v1.x Apr 4, 2026
24 checks passed
@jasonsaayman jasonsaayman deleted the feat/unify-docs branch April 4, 2026 18:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

commit::docs The PR is related to docs priority::medium A medium priority

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant