Skip to content

Migrate documentation site to Docusaurus and add branch-source versioning - #459

Open
VGalaxies wants to merge 21 commits into
masterfrom
docusaurus-issue-103-preview
Open

VGalaxies wants to merge 21 commits into
masterfrom
docusaurus-issue-103-preview

Conversation

@VGalaxies

@VGalaxies VGalaxies commented May 5, 2026

Copy link
Copy Markdown
Contributor

Summary

This PR migrates the HugeGraph documentation website preview to Docusaurus and adds branch-source documentation versioning.

Key changes:

  • Add Docusaurus-based site configuration, build scripts, and validation workflow
  • Replace committed Docusaurus version snapshots with generated version artifacts; npm run docs:versions:prepare regenerates them from configured Git source refs
  • Source Stable (1.7.0) from the temporary Docusaurus-native docusaurus-1.7.0 branch, while keeping Next on the current docs content
  • Add archived release entries in the documentation dropdown: 1.5.0, 1.3.0, 1.2.0, 1.0.0, 0.11, and 0.10
  • Make the version mapping explicit: release-* source branches map to docusaurus-* Docusaurus version routes, while UI labels stay user-friendly
  • Isolate pre-Docusaurus branch import repairs under legacyCompatibility; these adapters are compatibility-only for the archived release branches and are not part of the normal Docusaurus authoring pipeline
  • Prune archived-version duplicate Documentation pages for Download, CLA, and contribution guidelines when those pages already exist in global Download or Community sections
  • Add the Kapa Ask AI widget integration with the temporary HugeGraph website integration ID hardcoded, plus a TODO to move it to a GitHub repository variable later
  • Add a Pulsar-style .htaccess CSP override for the Kapa widget, hCaptcha, and Kapa proxy/metrics domains
  • Add an IoTDB-style compact Documentation navbar dropdown with reliable hover/click behavior and keyboard support
  • Preserve locale-aware navigation and language switching across Docs, Blog, Community, Team, Users, and Download pages
  • Move Download pages out of Docs and move contribution/CLA pages into Community
  • Localize non-badge external documentation images and keep documentation image references under local /img/... assets
  • Add an unlisted/noindex placeholder blog example for the private content visibility workflow
  • Keep generated Docusaurus version output directories ignored at the repository root so source docs remain the primary editing surface

Related Issue

Closes #103

Validation

  • npm run build
  • node scripts/validate-build.js
  • npm run validate:content
  • npm run validate:ui
  • npm run docs:versions:list
  • git diff --check
  • Kapa widget configuration smoke tests for default hardcoded ID and KAPA_WEBSITE_ID override behavior
  • Staged HTML check confirms https://widget.kapa.ai/kapa-widget.bundle.js is emitted with website ID 0b277570-4740-451e-96fa-1e4ac1ac5e88
  • Staged CSP header check confirms the Pulsar-style Kapa/hCaptcha allowlist is active
  • Playwright/Chromium check confirms the staged Ask AI launcher renders and opens the Apache HugeGraph AI Assistant consent modal without CSP errors
  • Dropdown interaction validation covers hover movement into the menu, click-to-keep-open behavior, outside-click close behavior, and mobile viewport sizing/overflow
  • Archived docs pruning validation checks that duplicate Download, CLA, and contribution guideline entries are absent from archived English and Chinese sidebars and that removed archived routes return 404
  • ASF staging preview updated at https://hugegraph.staged.apache.org/ from asf-staging commit 9fae5e8f
  • Version routes generated for /docs/, /docs/next/, /docs/docusaurus-1.5.0/, /docs/docusaurus-1.3.0/, /docs/docusaurus-1.2.0/, /docs/docusaurus-1.0.0/, /docs/docusaurus-0.11/, /docs/docusaurus-0.10/, and matching /cn/docs/... routes

@dosubot dosubot Bot added size:L This PR changes 100-499 lines, ignoring generated files. enhancement New feature or request labels May 5, 2026
@VGalaxies VGalaxies changed the title Migrate documentation site to Docusaurus Migrate documentation site to Docusaurus and add versioned docs May 6, 2026
@VGalaxies VGalaxies changed the title Migrate documentation site to Docusaurus and add versioned docs Migrate documentation site to Docusaurus and add branch-source versioning May 6, 2026
VGalaxies added 10 commits May 6, 2026 13:11
- New homepage: animated graph-network hero, quick-start terminal, feature
  and capability cards, layered ecosystem, and CTA (shared EN/CN component)
- Restyle Team and Users pages (stylized hero, metrics, member/case cards)
- Global design system in custom.css (tokens, dark mode, responsive, motion)
- Locale-aware footer; refine EN/CN copy and localize CN data labels
- Fix Kapa Ask AI launcher logo to a root-relative path

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request size:L This PR changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: use Docusaurus as the FE frame & improve theme style - css/js

1 participant