docs: scaffold forge.electronjs.org Docusaurus site

[claude]

Requested by Erick Zhao · Slack thread

Decisions (from the Slack thread): the site lives in this repo under website/; https://forge.electronjs.org is the canonical URL; the site is built from docs/ on next and published on every version tag (v*), not on pushes; v7 docs and electronforge.io (redirects, GitBook URLs) are out of scope for now.

Before: docs/ on next has 56 Docusaurus-flavoured pages (plus one partial) and a complete sidebars.ts, but nothing builds or publishes them; the public site is still the GitBook-era electronforge.io.

After: a standalone website/ Docusaurus 3.10 project builds ../docs at the site root (yarn build passes with onBrokenLinks: 'throw', 0 warnings, ~5 s). The Website workflow builds it on PRs that touch docs/, website/ or the workflow itself, and on every version tag (v*) — matching how the TypeDoc publish in #4385 triggers — builds and publishes it to forge.electronjs.org.

• I have read the contribution documentation for this project.
• I agree to follow the code of conduct that this project follows, as appropriate.
• The changes are appropriately documented (if applicable).
• The changes have sufficient test coverage (if applicable).
• The testsuite passes successfully on my local machine (if applicable).

Summarize your changes:

How.

• website/ is its own Yarn project (own yarn.lock, .yarnrc.yml pointing at the vendored ../.yarn/releases/yarn-4.18.0.cjs, nodeLinker: node-modules), deliberately not a monorepo workspace, so the root lockfile, yarn constraints, knip, oxfmt/oxlint and markdown lint are untouched — all of them still pass at the root with this branch checked out.
• docusaurus.config.ts points docs.path at ../docs with routeBasePath: '/' (so docs/index.md is the home page), staticDirectories: ['../docs/static', 'static'] so the existing /img/image.png reference resolves, and an editUrl function that maps to https://github.com/electron/forge/edit/next/docs/<file>. Navbar: Docs, API (packages.electronjs.org/forge/latest — not live yet), electronjs.org, GitHub; footer is minimal. React 19, @docusaurus/faster (Rspack/SWC), TypeScript 5.9 for yarn typecheck.
• website/sidebars.ts is a one-line re-export of docs/sidebars.ts, so the sidebar keeps living next to the content.
• One docs/ content edit: docs/import-existing-project.md loses the leftover GitBook layout: frontmatter block (11 lines). Nothing else in docs/ changed — no links, headings or partials needed touching; _partials/ is excluded by Docusaurus's default _* rule and the two partial imports resolve.
• The webpack icon was removed from the navbar (the site is Forge-wide, not webpack-specific).
• .github/workflows/website.yml: triggers on pull_request (path-filtered) and on push of v[0-9]+.[0-9]+.[0-9]+* tags. The build job installs, builds and uploads website/build as the website artifact on both; the deploy job runs on every version tag (v*) only — matching how the TypeDoc publish in ci: publish TypeDoc to packages.electronjs.org on version tags #4385 triggers — under the website-publish environment with id-token: write, downloads that artifact, logs in to Azure with azure/login via OIDC and azcopy syncs it into the storage account's $web container with --delete-destination=true --compare-hash=MD5. A forge-website-deploy concurrency group (no cancel) keeps two tag pushes from racing the sync. All actions are SHA-pinned; zizmor reports no findings.

Depends on

• electron/infra#352 — creates the forge.electronjs.org storage account / static website, DNS, the website-publish environment on this repo (deployment policy: tags matching v*, so the OIDC subject is repo:electron/forge:environment:website-publish) and the AZURE_FORGE_WEBSITE_OIDC_CLIENT_ID / AZURE_FORGE_WEBSITE_STORAGE_ACCOUNT_NAME secrets (AZURE_OIDC_TENANT_ID and AZURE_OIDC_SUBSCRIPTION_ID are the shared org values). Until that lands, the deploy job will fail at azure/login on the first version tag; the build job is unaffected.
• Hosting note for that PR: routes with a dot in the last segment (/config/makers/squirrel.windows) are emitted as squirrel.windows/index.html; the static website must not treat .windows as a file extension (Docusaurus's own serve falls back to the SPA shell for it).
• electron/infra#353 — Cloudflare Pages preview projects for PRs (not a merge dependency).

Known issues

• Socket Security flags two transitive Docusaurus dependencies as obfuscated code (copy-webpack-plugin, @pnpm/network.ca-file) — see docs: scaffold forge.electronjs.org Docusaurus site #4386 (comment). It is not a required check; a maintainer needs to triage/acknowledge them.

Follow-ups (not in this PR)

• Rewrite the ~43 https://js.electronforge.io/... links in docs/ (plus the "API Docs" entry in docs/sidebars.ts) once packages.electronjs.org/forge is live — they use the old _electron_forge_* TypeDoc slugs; the new format is _electron-forge_*.
• A real Forge logo and favicon (the scaffold ships placeholders).
• docs/cli.md has 9 H1 headings; it renders but the table of contents is flat.
• CONTRIBUTING.md and the issue template still point at the old docs repo.
• i18n (Crowdin) — the config declares en only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01P4HRbe7XtfgT6eVQZbjcUb

---

Generated by Claude Code

[socket-security]

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

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​docusaurus/​tsconfig@​3.10.2
	npm/​@​docusaurus/​faster@​3.10.2
	npm/​@​docusaurus/​module-type-aliases@​3.10.2
	npm/​@​docusaurus/​preset-classic@​3.10.2
	npm/​@​docusaurus/​types@​3.10.2
	npm/​@​types/​react-dom@​19.2.7
	npm/​@​docusaurus/​core@​3.10.2
	npm/​@​types/​react@​19.2.18
	npm/​react@​19.2.8
	npm/​@​mdx-js/​react@​3.1.1
	npm/​prism-react-renderer@​2.4.1
	npm/​react-dom@​19.2.8

View full report

[socket-security]

Caution

Review the following alerts detected in dependencies.

According to your organization's Security Policy, you must resolve all "Block" alerts before proceeding. It is recommended to resolve "Warn" alerts too. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Block		Obfuscated code: npm @pnpm/network.ca-file is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: website/package.json → npm/@docusaurus/core@3.10.2 → npm/@pnpm/network.ca-file@1.0.2 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@pnpm/network.ca-file@1.0.2. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Block		Obfuscated code: npm copy-webpack-plugin is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: website/package.json → npm/@docusaurus/core@3.10.2 → npm/copy-webpack-plugin@11.0.0 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/copy-webpack-plugin@11.0.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Low adoption: npm @11ty/gray-matter Location: Package overview From: website/package.json → npm/@docusaurus/core@3.10.2 → npm/@docusaurus/preset-classic@3.10.2 → npm/@11ty/gray-matter@1.0.0 ℹ Read more on: This package | This alert | What are unpopular packages? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Unpopular packages may have less maintenance and contain other problems. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@11ty/gray-matter@1.0.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[claude]

Working with Erick Zhao

Socket Security is red on this PR because two transitive dependencies of @docusaurus/core@3.10.2 are flagged "obfuscated code" (High): copy-webpack-plugin@11.0.0 (via @docusaurus/bundler) and @pnpm/network.ca-file@1.0.2 (via update-notifier → registry-auth-token → @pnpm/npm-conf), plus a Medium "low adoption" warning for @11ty/gray-matter@1.0.0 (via @docusaurus/utils, pulled in by @docusaurus/preset-classic). None of them are direct dependencies of this PR; they come with any Docusaurus 3.10 install. electron/website's lockfile (Docusaurus 3.10.0) resolves the same copy-webpack-plugin@11.0.0 and @pnpm/network.ca-file@1.0.2; @11ty/gray-matter only appears in the newer 3.10.2. The "obfuscated" heuristic is firing on their minified dist/ output.

I'm not overriding the org security policy from a bot account. If a maintainer agrees these are acceptable, the per-PR override is @SocketSecurity ignore npm/copy-webpack-plugin@11.0.0 and @SocketSecurity ignore npm/@pnpm/network.ca-file@1.0.2 (or triage them in the Socket dashboard so future Docusaurus PRs don't hit this). If not, this is a point against hosting the site scaffold in the forge repo and in favour of a separate repo or building from electron/website — see the open questions in the description.

---

Generated by Claude Code