Repository navigation
Make main branch the shared theme and governance branch for the multi-product docs - #1004
Closed
AmilaSamith wants to merge 73 commits into
Closed
AmilaSamith wants to merge 73 commits into
AmilaSamith wants to merge 73 commits into
Conversation
This workflow file manages the staging deployment for multiple product branches, ensuring that the `staging` branch is continuously updated with the latest changes from the specified product branches.
Converts main from the untouched pre-revamp branch into the product-agnostic template/governance branch every product branch forks from and syncs shared theme out of (CONTRIBUTING.md, MAINTENANCE.md, CODEOWNERS, HOW_TO_WRITE_A_GUIDE.md, UI_UX_GUIDELINES.md). Shared theme work: navbar (search dialog, responsive collapse/breakpoints, Learn Hub rename, icon fixes), sidebar (caret alignment, category badges, pinned Platform Overview with switchable scroll-to-active-section, full-width doc layout), footer (single-row layout), Explore dropdown badge support, CloudDocsLink for cross-site saas links, and a Community page overhaul. Connector catalog: sidebar scoping fix (baseUrl stripping), mobile search/filters, then shrunk to an inert stub outside wso2-connectors (the only branch that renders it) once that branch owned the real implementation. sync-theme.yaml hardening: multi-branch-safe gh-pages deploy, excludes ConnectorCatalog/ArtifactPicker's data.ts from the sync, stops wiping per-branch doc images, adds missing shared paths (ColorSwatch), syncs SidebarProductHeader fixes and guide-categorization docs from saas. This tree wholesale-replaces upstream/main's independent theme/content drift since PR wso2#647 (SAP SuccessFactors connector docs, genai agent identity docs, ICP/managed-service doc updates, and a parallel theme iteration) -- that content already has a home on the product branches under the new branch model; main carries no product content by design. See MAINTENANCE.md's "What main is for."
… by saas and wso2-integrator
…ad card rules from wso2-integrator Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
…ar dropdown The product pill now checks the target product's sitemap and links to the same page when it exists there, falling back to that product's home page. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
…of-sync note Matches the saas, wso2-integrator and wso2-connectors copies so the theme sync no longer reverts the per-branch group. The saas /saas/ subpath and root redirect steps the note described are already in this file. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Shared theme rebase
Remove unnecessary files
This workflow synchronizes shared theme and governance documents from the main branch to specified product branches, ensuring consistency across visual identity and documentation.
…s saas Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Shared theme rebase
…:// link handling Adds crossProductLinks.js (remark plugin, synced to every branch) and makes the MDX anchor skip baseUrl for pathname:// links, so docs can link to a sibling product without a hardcoded production path. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Add shared product:// cross-product link plugin and pathname:// link handling
When FORK_BASE_PATH is set (a personal fork's Pages demo), inject <meta name="robots" content="noindex, nofollow"> into every built page and the root redirect, and drop the sitemaps. A robots.txt can't do this on a project site, since crawlers only read it from the host root. Real org builds don't set FORK_BASE_PATH, so production and staging are unaffected. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
ci(staging): add noindex to fork builds so the demo isn't indexed
Markdown export now names files by Docusaurus doc id (taken from the docs plugin) so the Copy page / View as Markdown URLs resolve for sites with a custom docs path (connectors) and for folder index pages. Download as PDF now prints after the menu closes, and the print stylesheet hides the Copy page dropdown and floating action buttons that were repeated on every printed page. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Give the FloatingActions wrapper a stable class the print stylesheet can target, and add FloatingActions and ReportIssueButton to sync-theme.yaml's trigger paths so edits to them sync to product branches. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Add copy page, Copy as markdoen and Download PDF fixes
Add Shared Theme
[shared-doc-theme] Add AI Docs Assistant side panel UI
A ## with no body of its own (such as the group headings in the FAQ) followed straight by a ### drew the h2's bottom rule and the h3's top rule back to back. Drop the h3's top rule and padding in that case so only the h2's rule shows. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Fix adjacent heading rules
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Update codeowners and contribution guidelines
AmilaSamith
requested review from
KavinduZoysa,
NipunaRanasinghe,
anupama-pathirage and
rosensilva
as code owners
October 16, 2026 11:31
Contributor
WalkthroughWarning Review details and warnings were omitted to fit the comment limit. |
Broken links, images & orphan pages
Links/images come from one crawl of the production build (baseUrl-aware). Orphans are docs not referenced by Summary
Broken links & imagesIntroduced by this PRThis PR introduces 14 broken link(s)/image(s): Show 14
Already on
|
Contributor
Author
|
Reviewers please ignore the broken link since this branch don't contain any product code. We will remove that workflow in future. |
anupama-pathirage
previously approved these changes
Oct 16, 2026
Promotes this session's shared-component work (already live on wso2-integrator and saas) to main, the canonical source sync-theme.yaml fans out from: warm single-header navbar/sidebar/search/footer, the version pill system (ICP badge+version, page-level pill), quickstart components (QuickstartHeader/Prerequisites/Steps/DocFeedback), hero zoom + search guard, CookieConsent, and the product/version switcher rework (drop per-product descriptions, "Current" marker, reordered version dropdown). Also extends sync-theme.yaml's SHARED_PATHS (+ MAINTENANCE.md's own bullet, kept in sync by hand per that file's own instruction) with four components that were missing from it entirely: QuickstartHeader, Prerequisites, and Steps (globally registered by the already-shared theme/MDXComponents, so any sync target missing them fails to build the moment it receives that file), DocFeedback (rendered by the already- shared theme/TOC), and CookieConsent (mounted by theme/Root.js, reopened from theme/Footer -- both already shared). Also adds the two PNG navbar logo files themeConfig.ts now references, replacing stale SVG-only entries in the same list. Fixes main's own pages/index.tsx to match LandingHero's updated prop shape (title now accepts ReactNode; the old `badge` prop was dropped in favour of `eyebrow` earlier this session) -- pages/* isn't synced, so this file needed its own one-line fix to keep building once the shared LandingHero landed under it. platform-overview/ and the rest of the shared DOCS CONTENT are deliberately NOT part of this promotion: that already has its own sync path (wso2-integrator -> saas via sync-content-to-saas.yaml, see AGENTS.md's Golden Rule 1), unrelated to this theme/chrome promotion, and main is documented as still being the pre-revamp content branch until a separate, deliberate migration happens.
…m-overview up to date main's own per-branch content (pages/*, docusaurus.config.ts's navbar items, docs content -- none of this is synced by sync-theme.yaml) had fallen behind the shared components it now carries: - pages/index.tsx + index.module.css: rebuilt to the same warm-theme structure every real product branch uses -- hero search, a "New to this scaffold?" 4-step strip + quickstart tiles, and an "Explore the scaffold" section (banner + lifecycle grid + wide tile), reusing this branch's own existing scaffold sections/icons rather than copying a real product's content. - docusaurus.config.ts: navbar rewritten to the single-header pattern (Blog/Community/Contribute/FAQ/GitHub + a CTA button), replacing the pre-redesign "Connectors" self-link + "Explore" mega-dropdown so a new product branch forking from this scaffold starts from the current pattern, not the old one. Also adds the matching H2/H3-only tableOfContents setting. - Both scaffold quickstart docs (build-integration-api, build-ai-agent) migrated to QuickstartHeader/Prerequisites/Steps, demonstrating the pattern a real product's own quickstarts use. - platform-overview/platform-overview.md: content refreshed to wso2-integrator's current real copy (a full rewrite since this was last copied here), plus its four referenced images. This is a one-time manual content refresh, not a new ongoing sync path -- platform-overview already has its own sync (wso2-integrator -> saas via sync-content-to-saas.yaml, see AGENTS.md's Golden Rule 1), and main stays the documented pre-revamp content branch otherwise.
Node's default old-space heap isn't enough once a branch carries more than one versioned_docs/ snapshot -- wso2-integrator's own 5.1.0 cut crashed this build step with "JavaScript heap out of memory". Raise it only for that branch's case entry instead of unconditionally for every branch, since saas/wso2-connectors don't carry that weight yet; add the same line to a branch's own entry once it does (e.g. after its first docs:version cut). Co-Authored-By: Claude Sonnet 5 <[email protected]>
The orange active-item indicator bar (a position:absolute ::before, left: 0 relative to .menu__link) sat 11px to the right of the nested .menu__list's own vertical guide line (its border-left, pushed out by padding-left: 10px + the border's own 1px) -- a visible gap between two parallel vertical lines instead of the active bar reading as a highlighted continuation of the parent's line. left: -11px cancels that inset so both lines sit at the same x position. Co-Authored-By: Claude Sonnet 5 <[email protected]>
…flush fix(theme): flush sidebar active-item bar with parent guide line
saas's own commit (09026dc, "support a smaller trailing title suffix") added a TitleSuffix export directly to LandingHero/index.tsx -- a wholesale-synced shared file. The next sync-theme run from main overwrote it with main's version, which never had TitleSuffix, silently dropping the export. saas's own pages/index.tsx (per-branch, not synced) still imports and renders <TitleSuffix>, which now resolves to undefined -- "Element type is invalid ... got: undefined" at build, failing SSG for "/saas/". Ports the same addition (title: ReactNode instead of string, the TitleSuffix component, its .heroTitleSuffix CSS) onto main's copy so it's the shared source of truth and survives future syncs, instead of living only on saas where every re-sync wipes it. Co-Authored-By: Claude Sonnet 5 <[email protected]>
fix(theme): port LandingHero's TitleSuffix from saas onto main
fix(ci): scope staging_sync's raised Node heap to wso2-integrator
… logic into shared Sidebar Four recurring incidents this session (CI heap-size config, a connector header component, a shared LandingHero helper, and a connector sidebar switcher) all had the same root cause: a product branch hand-edited a file under sync-theme.yaml's SHARED_PATHS to add branch-specific behavior, and the next sync from main silently reverted it because main has no knowledge the addition exists. One of those -- the sidebar scoping in theme/DocRoot/Layout/Sidebar -- had actually leaked a hardcoded "Connector Catalog" check into main itself from an earlier promotion, which is backwards for a file every product branch shares. Adds en/src/theme-local/ as a permanent, documented escape hatch: deliberately excluded from SHARED_PATHS (same as docusaurus.config.ts / pages/index.*), so a sync from main never touches it. Two extension points, each with a safe no-op default every branch keeps a copy of: - RootExtras (theme/Root.js): mount something globally, e.g. a connector-only sidebar switcher. - sidebarTransform (theme/DocRoot/Layout/Sidebar): transform the sidebar tree per-request, e.g. scope it down to one connector's own pages. Strips the hardcoded connector-scoping logic out of DocRoot/Layout/Sidebar entirely -- it's now a pure, product-agnostic pass-through to sidebarTransform, with no idea what a "connector" is. Also promotes DocSidebarItem/Html's "render a real React <div> for a portal mount point instead of dangerouslySetInnerHTML" fix as a fully generic capability (customProps.portalSlotId), not connector-specific, since any sidebarTransform on any branch might need the same portal mount pattern. Documents the whole mechanism in MAINTENANCE.md and sync-theme.yaml's own SHARED_PATHS comment, so the next person hits the doc before hitting the bug. Co-Authored-By: Claude Sonnet 5 <[email protected]>
…ints feat(theme): add theme-local/ extension points, stop baking connector…
rosensilva
reviewed
Oct 19, 2026
This workflow is workflow_dispatch-only and intentionally fork-specific (its own header comment: "NOT part of the real pipeline") -- it builds with this fork's own /docs-integrator/ base paths and force-replaces gh-pages outright (no keep_files). Manually running it on the real org repo would overwrite production with a wrongly-based-URL'd preview build, bypassing promote_to_production.yaml's staging-review-then- promote flow entirely. Adds a job-level `if: github.event.repository.fork == true` guard -- false on wso2/docs-integrator, true on any fork, so the job can still run exactly where it's meant to. Co-Authored-By: Claude Sonnet 5 <[email protected]>
… agent run_claude's only gate was contains(comment.body, '@wso2-engineering-bot') -- issue_comment fires for a comment from any GitHub user, so without an author check, anyone could comment the trigger phrase on any issue and get this job to run with DOC_FIXING_AGENT_GITHUB_TOKEN (push-capable) and a Claude run whose --allowedTools include Bash(git push *) and mcp__github__create_pull_request. The pre-commit hook's path whitelist and the system prompt's jailbreak/ hidden-instruction guards already bound the worst-case damage (docs/ images only, resistant to prompt injection), but an untrusted comment still shouldn't be able to spend Anthropic API budget / Actions minutes or get an unreviewed bot PR opened at all. Adds an author_association check (OWNER/MEMBER/COLLABORATOR) alongside the existing trigger-phrase check. Whichever of those the DOC_FIXING_AGENT_GITHUB_TOKEN account's own comments (the scheduled flow in get_issue_and_assign) resolve to needs to stay on this list for that flow to keep working -- worth confirming after this merges. Co-Authored-By: Claude Sonnet 5 <[email protected]>
--fail-on-any means every single PR into main goes red over the same ~14 pre-existing broken links (dead links to not-yet-written pages like deploy/cloud/overview.md, two connector setup guides, and two /skills/*.skill 404s from one source page) regardless of what that PR actually touches -- confirmed this isn't a regression, it's been true since at least Oct 8th. Not a required status check, so it never blocked merging, but the constant red was pure noise. Switches the trigger from `pull_request: branches: [main]` to workflow_dispatch with a base_ref input (defaults to main), so it's still available on demand (e.g. after a doc restructure, to get the introduced-vs-already-on-main breakdown) without firing on every PR. Updates the two PR-context-dependent steps (base branch checkout, PR comment artifact) to work from workflow_dispatch instead of pull_request context -- the PR-number step now looks up whether the current ref happens to have an open PR via `gh pr list`, so a manual run against a PR's own branch still gets its comment, and a run with no matching PR just skips that step cleanly. Co-Authored-By: Claude Sonnet 5 <[email protected]>
Add preview guard
rosensilva
approved these changes
Oct 19, 2026
Contributor
Author
Contributor
Author
|
Closing this PR since twin PRs sent are merged. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Turns
mainfrom the single-site docs branch into the product-agnostic template and governance branch for the multi-product setup described inMAINTENANCE.md. Product documentation now lives on the product branches (saas,wso2-integrator,wso2-connectors), andmainholds the shared theme, the shared workflows and the contributor docs.This PR deletes a lot of content from
main. About 4,400 files change, mostly deletions of the old flat docs (en/docs/connectors,develop,manage,reference,deploy-operate,genai,deployand others). That content is not lost. It is authored on the product branches, and nothing deploys frommainany more (see "Deployment impact").What changes
Shared theme and components
en/src/theme/,theme-shared,custom.css) and the shared components:SiteNav,SidebarProductHeader,ExploreDropdown,ProductDocsLinks,GuidesCatalog,PaletteCard,PaletteIcon,IconGallery,ColorSwatch,SearchBar,LandingHero,ArtifactPicker,AiAssistantPanel,AIAssistantSidePanel,FloatingActions,ReportIssueButton.ConnectorCatalogis no longer onmain. It is owned bywso2-connectors.LandingHerois the shared homepage hero. Each product passes its own copy and its ownstatic/img/landing/hero.png.Workflows
staging_sync.yaml: on every push to a product branch, builds that branch into its own folder on thestagingbranch.promote_to_production.yaml: a manual run that publishes a taggedstagingtree togh-pageswith no rebuild.sync-theme.yaml: when shared paths change onmain, opens a bot PR into each product branch.fork_preview.yaml.publish_docs.yaml, so a push tomaincan no longer build the scaffold and deploy it over the live site.Governance docs
CONTRIBUTING.md,MAINTENANCE.md,AGENTS.md,HOW_TO_WRITE_A_GUIDE.mdandUI_UX_GUIDELINES.md.CONTRIBUTING.mdhas real section owners and notes which files inside theshared folders are not synced.
CODEOWNERSis updated formain: @anupama-pathirage, @keizer619, @AmilaSamith.Scaffold docs
section-1,section-2,guides,get-started,platform-overview,icons,homepage,workflows,tools,reference) that documents how the template works.Deployment impact
publish_docs.yamlgone, no workflow runs on a push tomain, exceptsync-theme.yamlwhen shared paths changed.gh-pages. It only changes when a maintainer runs Promote to Production frommain's Actions tab with a tag on thestagingtip.gh-pagescompletely with thestagingtree. The old flat site at the root ofgh-pagesis removed, and its URLs will 404 unless redirects are added. This is a separate step from this PR.Before and after merging
chore/remove-main-publish-docsand the CODEOWNERS and CONTRIBUTING commits are in this PR.saas,wso2-integrator,wso2-connectors), only if their shared paths differ frommain.stagingis current for all three products before any promote. At the time of writing,wso2-integratorandwso2-connectorswere behind onstaging.FORK_BASE_PATHvariable is unset, and branch protection allows Actions pushes tostagingandgh-pages.Testing
docusaurus buildandtscwere run on the feature branches.wso2/docs-integratoritself.