docs: take Defang Deploy one layer down from the section landing

[defang-sam]

Follow-on to #430, which named the product only where a sentence defined it. This takes the titles, descriptions, h1s and first defining sentence of the Deploy section — the layer a reader actually sees.

A correction to #430's reasoning first

That PR left the intro.mdx h1 as "Defang Documentation" on the grounds it was the docs site root. It is not. The root is a separate custom page, src/pages/index.tsx, serving docs.defang.io/ with its own title of "Defang":

docs.defang.io/           class="plugin-pages plugin-id-default"   <title>Defang</title>
docs.defang.io/docs/intro  the Deploy section landing (intro.mdx)

intro.mdx is the Deploy section's own landing, reached from the "Defang Deploy" navbar tab. So it now reads "Defang Deploy Documentation".

What changed

Page	Title	Description	H1	Opening sentence
Overview (intro.mdx)	—	done in #430	✅	done in #430
What is Defang? → What is Defang Deploy?	✅	✅	✅	✅
Features	—	✅	✅	✅
Use Cases	—	✅	✅	✅
Getting Started	—	✅	—	✅
FAQ	—	✅	done in #430	done in #430
How it Works	—	done in #430	done in #430	done in #430

The real site root keeps its Defang Documentation h1 — that page genuinely does cover both products. Its product sentence and its card now say Defang Deploy, because both describe Deploy specifically. The same card text in getting-started.mdx is kept in step with the copy #430 already fixed in intro.mdx.

What was not touched

• URLs, including /docs/intro/what-is-defang. Renaming the file would break inbound links for the sake of a heading, and the style guide treats URLs as identifiers rather than copy.
• All 14 Defang CLI references in the section. The CLI keeps its name, so "Install the Defang CLI" and every defang command stay. Verified: zero instances of "Defang Deploy CLI" were introduced.
• Body copy below the first defining sentence. Still bare "Defang", deliberately — by then the page heading has named the product, which is the condition the style guide sets.

One thing I'd like your call on

The docs root landing does not mention Station at all. Its four cards are "Learn more about Defang Deploy", "Agent Skills", "CLI Reference", "Deploy to your own cloud" — and Station has had a docs section since it was added to the navbar.

That is the same gap you asked me to close on the AI-facing surfaces in #3266, so I suspect the answer is the same. But it adds a card rather than renaming one, so I left it out and am asking instead. One line if you want it.

Verification

• docusaurus.config.js parses
• Frontmatter intact on all six markdown files
• src/pages/index.tsx syntax valid
• 14 Defang CLI references intact, 0 wrongly renamed
• test-deploy build green on this PR

As on #430, a local docusaurus build cannot run here: prebuild shells into ../defang/src/cmd/gendocs and needs Go. It fails identically on clean main, so I am relying on this PR's build.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 4e2e57ac-b1e8-4acd-b63b-e3faa5e862c9

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[defang-sam]

Three updates from review

1. Station is now on the docs landing

docs.defang.io/ had four cards, all Defang Deploy, and never mentioned Station. It now carries a Station card beside the Deploy one:

Learn more about Defang Deploy    What is Defang Deploy and how does it work?
Learn more about Defang Station   An always-on machine for your coding agent.
Agent Skills                      Deploy from your agent
CLI Reference                     Use the Defang CLI to deploy your app
Deploy to your own cloud          When you're ready for production

2. You were right about "Defang includes the following features"

Stopping at the first sentence left one paragraph naming the product two ways:

"Defang Deploy provides a streamlined experience… Defang includes the following features:"

The "context has already named it" rule works across sections, not across adjacent sentences. Rule tightened:

In these top-layer pages, a sentence claiming what the product does or supports says "Defang Deploy".

40 mentions across five pages. Deliberately still bare, because they are company-level or are names that do not change:

Stays bare	Why
13 × Defang CLI, every defang command	The CLI keeps its name
login, authentication, "if you have not used Defang before"	Identity is company-level and shared by all three products
Defang Discord, the repo, the logo alt text	Names and identifiers
Terminal output in code blocks	Not copy

Verified: zero instances of Defang Deploy CLI, Defang Deploy Discord or Defang Deploy account introduced.

3. Seven FAQ headings would have broken their anchors

Docusaurus derives heading IDs from the text, so renaming a heading changes its anchor and breaks external deep links. All seven now pin their original anchor.

This also repairs a regression from #430. Live on production right now:

can-i-run-production-apps-with-defang            ← original, would have broken
does-defang-support-auto-scaling                 ← original, would have broken
does-defang-support-bluegreen-deployments        ← original, would have broken
does-defang-support-rolling-deployments          ← original, would have broken
is-defang-deploy-a-run-time-platform             ← #430 already broke this one
what-is-the-difference-between-defang-deploy-…   ← #430 already broke this one
what-is-the-difference-between-defang-deploy-…   ← #430 already broke this one

Pinning restores all seven to the anchors that had been live for years.

One thing I got wrong and fixed: I first used Docusaurus's {#id} syntax. This site sets markdown.format: "mdx", so every .md is parsed as MDX and {#id} is a JSX expression — the build died with "Could not parse expression with acorn". Plain <a id="…"></a> before each heading does the same job and parses. Caught by running the real build, not by inspection.

---

Preview

There is no automatic preview for this repo — test-deploy.yml only builds, it does not publish or upload an artifact. So I installed Go, ran the real prebuild + build, and am serving it:

Open the preview

Worth looking at: the landing (Station card), /docs/intro/ (Defang Deploy Documentation), /docs/intro/what-is-defang.html, and /docs/intro/faq/questions.html.

The link is time-limited — ask and I will mint a fresh one. If a hosted preview per PR would be useful going forward, adding an artifact upload or a preview deploy to test-deploy.yml is a small change; say the word and I will open it separately.

Build

Full prebuild + build passes locally with Go installed. The two broken-anchor warnings it reports are on /docs/concepts/mcp and /docs/providers/aws — pre-existing, on pages this PR does not touch.

[defang-sam]

Landing is now a two-product chooser

You were right on all three points. It said "Defang Documentation", described only Deploy underneath, then offered a mix of Deploy and Station cards.

Before

Defang Documentation
"Defang Deploy lets you take your app from Docker Compose to a secure and
 scalable deployment on your favorite cloud in minutes. Build cloud applications
 in any language and stack…"

Getting Started
  Learn more about Defang Deploy   |  Learn more about Defang Station
  Agent Skills                     |  CLI Reference
  Deploy to your own cloud

After

Defang Documentation
"Defang helps you become AI-native without becoming vendor-native.
 Your cloud, your models, your accounts. Start with the product you are using."

Products
  Defang Deploy    Take your app to your own cloud on AWS, GCP or Azure.
  Defang Station   An always-on machine for your coding agent.

The sentence moves up to the company level, so it matches the h1 above it rather than contradicting it. The heading becomes Products, since two product cards are a chooser rather than a getting-started list.

Where the other three cards went

• CLI Reference and Deploy to your own cloud were already on the Defang Deploy page — they were duplicates, now removed from the landing.
• Agent Skills was not, so it moves to the Deploy page rather than being dropped.

The Defang Deploy page now carries all four, which is where a reader who has chosen a product expects them:

Learn more about Defang Deploy  |  Agent Skills
CLI Reference                   |  Deploy to your own cloud

Forge is deliberately absent. It has no docs section, and a card pointing nowhere is worse than no card.

Verified in the built site

root card count            2
root Deploy card href      /docs/intro          200
root Station card href     /docs/station        200
Deploy page card count     4
full prebuild + build      success, no new broken links

Refreshed preview

Open the preview

Now served by docusaurus serve rather than a plain static server, so extensionless routes like /docs/station resolve exactly as they do in production. Time-limited as before; ask for a fresh one.

[defang-sam]

You were seeing a cached copy — here is proof, and a fresh origin

The fix is on the branch and in the build. What you clicked was your browser's cached copy of the earlier build, because both preview links pointed at the same host and port.

What is actually being served, screenshotted just now in a clean browser

Two cards. Count them.

Measured in the same run, from a fresh browser context with no cache:

cards: 2
   - Defang Deploy    Take your app to your own cloud on AWS, GCP or Azure.
   - Defang Station   An always-on machine for your coding agent.

lede: Defang helps you become AI-native without becoming vendor-native.
      Your cloud, your models, your accounts. Start with the product you are using.

The old sentence you quoted — "Defang Deploy lets you take your app from Docker Compose…" — is gone from the landing. It lives on /docs/intro, the Defang Deploy page, where it belongs.

A different port, so your browser has no cache entry for it

Open the preview on the fresh origin

Port 4401 rather than 4400, same build. A new origin means no cache entry, so this cannot show you a stale page. Verified on it directly:

/                2 cards
/docs/intro      200
/docs/station    200

If you would rather stay on the old link, a hard reload (Cmd-Shift-R) will do the same job.

My mistake for handing you a second link at the same address as the first. A rebuilt site at an unchanged URL is exactly the setup where a browser serves the old one and it looks like nothing happened.

The screenshot lives on a separate preview/docs-431-landing branch, not on this PR's branch, so it is not part of the change.