Skip to content

feat(docs): two-product shell and the approved tagline (WS4) - #422

Merged
raphaeltm merged 1 commit into
mainfrom
feat/ws4-two-product-docs
Sep 8, 2026
Merged

raphaeltm merged 1 commit into
mainfrom
feat/ws4-two-product-docs

Conversation

@defang-sam

@defang-sam defang-sam Bot commented Sep 7, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Ready for review, but NOT ready to merge.

This PR puts the product names on public surfaces, and they are not announced yet. Merging publishes them. Please review and approve, then leave it for the announcement.

Why

Two things: the docs carried a tagline nobody decided on, and they had no room for a second product.

1. There was a fourth tagline

docusaurus.config.js:20 read:

"A radically simpler way to build and deploy production-ready cloud apps"

That is not the company tagline, not the product tagline, and not the retired Cloud, Simplified. It is a fourth line. Replaced with the product tagline — the docs serve developers, so that is the right level, and it invents nothing.

2. Two-product shell — ADD, do not move

Every one of the 84 existing doc URLs is unchanged. No entry in redirects.json was touched, and no new redirect was needed. Moving instead of adding would have meant ~84 new redirects on top of the 49 already there.

The five sections that were top-level navbar items are now grouped in a Deploy dropdown:

Before (navbar) After (navbar)
Overview, Tutorials, Concepts, Providers, CLI Deploy ▾ (Overview, Tutorials, Concepts, Providers, CLI)
— Station

Added docs/station/station.mdx at /docs/station plus a stationSidebar. It says plainly that Station is in development, and contrasts the two products so a reader who lands there is not confused.

Verification

Local docusaurus build: exit 0.

Check Result
/docs/intro, /docs/concepts, /docs/tutorials, /docs/providers all still build
/docs/station builds
Rendered navbar on /docs/intro one Deploy dropdown + one Station, with the five sections inside

One thing reviewers should know

npm run build runs scripts/prebuild.sh, which needs Go to generate docs/cli. Without Go the CLI sidebar is empty and then every page fails to render:

DocSidebarNavbarItem: Sidebar with ID "cliSidebar" doesn't have anything to be linked to.

That reproduces on clean main (89 failing paths there, 90 here — the extra one is the new Station page failing for the same reason). It is environmental, not caused by this change. I verified my change by stubbing docs/cli locally, building green, then removing the stub. docs/cli/.gitignore and _category_.json are untouched in the final diff.

Context

  • DefangLabs/defang-global#135 — the naming source of truth, including which tagline each surface takes
  • DefangLabs/defang-mvp#3232 — WS3, the website side
  • Plan and open items: SAM idea 01M1YE64QV7YFRA2B1B7YG9AWR

🤖 Generated with Claude Code

Tagline: docusaurus.config.js carried a FOURTH tagline nobody had decided on
("A radically simpler way to build and deploy production-ready cloud apps").
Replaced with the product tagline, which is what a docs site should carry.

Structure: ADD, do not move. Every one of the 84 existing doc URLs is
unchanged, so none of the 49 entries in redirects.json needed touching and no
new redirect was added. The five sections that were top-level navbar items
(Overview, Tutorials, Concepts, Providers, CLI) are now grouped in a "Deploy"
dropdown, and "Station" is a new top-level item.

Added docs/station/station.mdx as a placeholder at /docs/station, plus a
stationSidebar entry. It states plainly that Station is in development and
contrasts the two products.

Verified with a local docusaurus build: exit 0, /docs/intro, /docs/concepts,
/docs/tutorials and /docs/providers all still build, /docs/station builds, and
the rendered navbar shows one Deploy dropdown plus Station.

Note for reviewers: `npm run build` runs scripts/prebuild.sh, which needs Go to
generate docs/cli. Without it the CLI sidebar is empty and EVERY page fails to
render ("Sidebar with ID cliSidebar doesn't have anything to be linked to").
That happens on main too and is not caused by this change.

NOT ANNOUNCED: this puts "Defang Station" and "Deploy" on public docs. Hold
until launch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@defang-sam
defang-sam Bot marked this pull request as ready for review September 7, 2026 23:30
@defang-sam
defang-sam Bot requested a review from a team as a code owner September 7, 2026 23:30
@raphaeltm
raphaeltm requested a review from defangdevs September 8, 2026 10:23

@defangdevs defangdevs left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Reviewed the diff (docs/station/station.mdx, docusaurus.config.js, sidebars.js) against DefangLabs/defang-global#135 (merged naming source of truth):

  • Tagline: docs/station.mdx and docusaurus.config.js use "Develop Once, Deploy Anywhere." — matches the Defang Deploy product-level tagline in the guide exactly (right level for a developer-facing surface).
  • Navbar: all 5 previously top-level items keep their existing routes/sidebar IDs unchanged, just regrouped under a new "Deploy" dropdown — confirms no redirects were needed.
  • stationSidebar → docs/station wired correctly in sidebars.js; single-page autogenerated sidebar doesn't need a _category_.json.
  • CI green (Analyze, CodeQL, Test deployment).

No blocking issues. Agreed this should sit unmerged until the announcement per the PR warning — not merging.

@raphaeltm
raphaeltm merged commit ac3d9c7 into main Sep 8, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants