[Durable Objects] restructure docs around Diátaxis framework by elithrar · Pull Request #28345 · cloudflare/cloudflare-docs

elithrar · 2026-02-14T17:52:29Z

Structure (Diátaxis framework)

durable-objects/
├── index.mdx                              Overview (order 1)
├── get-started.mdx                        Get started (order 2)
│
├── concepts/                              Concepts — explanation (order 3)
│   ├── how-durable-objects-work.mdx       NEW — merged from what-are-durable-objects
│   │                                             + durable-object-lifecycle
│   │                                             + reference/in-memory-state
│   ├── storage-and-state.mdx              NEW
│   ├── calling-durable-objects.mdx        NEW
│   └── rules-of-durable-objects.mdx       MOVED from best-practices/ (content refreshed)
│
├── how-to/                                How-to guides — NEW section (order 4)
│   ├── access-storage.mdx                 ← best-practices/access-durable-objects-storage
│   ├── invoke-methods.mdx                 ← best-practices/create-durable-object-stubs-and-send-requests
│   ├── use-websockets.mdx                 ← best-practices/websockets
│   ├── handle-errors.mdx                  ← best-practices/error-handling
│   ├── use-alarms.mdx                     NEW — merged from api/alarms (how-to parts)
│   │                                             + examples/alarms-api
│   ├── configure-migrations.mdx           ← reference/durable-objects-migrations
│   ├── configure-data-location.mdx        ← reference/data-location
│   ├── use-environments.mdx               ← reference/environments
│   ├── test-durable-objects.mdx           ← examples/testing-with-durable-objects
│   └── gradual-deployments.mdx            external_link → Workers gradual deployments
│
├── api/                                   API reference (order 5, renamed from "Workers Binding API")
│   ├── base.mdx                           pcx_content_type fixed: concept → reference
│   ├── namespace.mdx                      "
│   ├── id.mdx                             "
│   ├── stub.mdx                           "
│   ├── state.mdx                          "
│   ├── sqlite-storage-api.mdx             "
│   ├── legacy-kv-storage-api.mdx          "
│   ├── alarms.mdx                         "
│   ├── container.mdx                      "
│   ├── webgpu.mdx                         unchanged (pcx_content_type: configuration)
│   ├── workers-rs.mdx                     external_link (unchanged)
│   └── rest-api.mdx                       external_link ← durable-objects-rest-api.mdx (root)
│
├── examples/                              Examples (order 6, was 8)
│   ├── build-a-counter.mdx                unchanged
│   ├── websocket-server.mdx               unchanged
│   ├── websocket-hibernation-server.mdx   unchanged
│   ├── durable-object-in-memory-state.mdx unchanged
│   ├── durable-object-ttl.mdx             unchanged
│   ├── reference-do-name-using-init.mdx   unchanged
│   ├── readable-stream.mdx                unchanged
│   ├── use-kv-from-durable-objects.mdx    unchanged
│   └── agents.mdx                         external_link (unchanged)
│
├── tutorials/                             Tutorials (order 9)
│   └── build-a-seat-booking-app.mdx       unchanged
│
├── observability/                         Observability (order 8, was 7)
│   ├── troubleshooting.mdx                unchanged
│   ├── metrics-and-analytics.mdx          fixed pre-existing <Steps> build error
│   └── data-studio.mdx                    unchanged
│
├── platform/                              Platform (order 9, was 12)
│   ├── pricing.mdx                        unchanged
│   ├── limits.mdx                         unchanged
│   ├── storage-options.mdx                external_link (unchanged)
│   ├── data-security.mdx                  ← reference/data-security
│   ├── faq.mdx                            ← reference/faq
│   ├── glossary.mdx                       ← reference/glossary
│   └── known-issues.mdx                   unchanged
│
├── demos.mdx                              unchanged (order 10)
├── video-tutorials.mdx                    unchanged (order 11)
└── release-notes.mdx                      unchanged (order 20)

DELETED sections: best-practices/, reference/

Content movements

best-practices/* dissolved — 4 how-to pages moved to how-to/, rules page moved to concepts/ (content refreshed with updated examples)
reference/* dissolved — 3 how-to pages moved to how-to/, 3 reference pages moved to platform/, 1 explanation page (in-memory-state) merged into concepts/how-durable-objects-work
examples/testing-with-durable-objects → how-to/test-durable-objects (it is a how-to, not an example)
examples/alarms-api content merged into new how-to/use-alarms
concepts/what-are-durable-objects + concepts/durable-object-lifecycle + reference/in-memory-state merged into new concepts/how-durable-objects-work
durable-objects-rest-api.mdx moved into api/rest-api.mdx (now an external_link redirect to the API docs)
All 9 API pages: pcx_content_type changed from concept to reference
All internal links updated across 48+ files (including partials, changelogs, workers docs, agents docs)
All new code examples are TypeScript-first using TypeScriptExample, with typed DurableObject<Env>, RPC methods, and this.ctx.storage
21 new redirects added, 13 existing redirects updated to point to new destinations
Fixed pre-existing <Steps> build error in observability/metrics-and-analytics

Redirects

All old paths have 301 redirects in public/__redirects:

Old path	New path
`/durable-objects/best-practices/`	`/durable-objects/how-to/`
`/durable-objects/best-practices/access-durable-objects-storage/`	`/durable-objects/how-to/access-storage/`
`/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/`	`/durable-objects/how-to/invoke-methods/`
`/durable-objects/best-practices/websockets/`	`/durable-objects/how-to/use-websockets/`
`/durable-objects/best-practices/error-handling/`	`/durable-objects/how-to/handle-errors/`
`/durable-objects/best-practices/rules-of-durable-objects/`	`/durable-objects/concepts/rules-of-durable-objects/`
`/durable-objects/reference/`	`/durable-objects/concepts/`
`/durable-objects/reference/durable-objects-migrations/`	`/durable-objects/how-to/configure-migrations/`
`/durable-objects/reference/data-location/`	`/durable-objects/how-to/configure-data-location/`
`/durable-objects/reference/environments/`	`/durable-objects/how-to/use-environments/`
`/durable-objects/reference/in-memory-state/`	`/durable-objects/concepts/how-durable-objects-work/`
`/durable-objects/reference/data-security/`	`/durable-objects/platform/data-security/`
`/durable-objects/reference/faq/`	`/durable-objects/platform/faq/`
`/durable-objects/reference/glossary/`	`/durable-objects/platform/glossary/`
`/durable-objects/reference/durable-object-gradual-deployments/`	`/durable-objects/how-to/gradual-deployments/`
`/durable-objects/concepts/what-are-durable-objects/`	`/durable-objects/concepts/how-durable-objects-work/`
`/durable-objects/concepts/durable-object-lifecycle/`	`/durable-objects/concepts/how-durable-objects-work/`
`/durable-objects/examples/testing-with-durable-objects/`	`/durable-objects/how-to/test-durable-objects/`
`/durable-objects/examples/alarms-api/`	`/durable-objects/how-to/use-alarms/`
`/durable-objects/durable-objects-rest-api/`	`/durable-objects/api/rest-api/`

Drift from original PR description

The following items differ from the original PR description tree:

rules-of-durable-objects.mdx content was refreshed, not "unchanged" as originally stated — the diff shows 343 additions / 326 deletions
api/rest-api.mdx is an external_link stub, not a moved content page — it redirects to /api/resources/durable_objects/
how-to/gradual-deployments.mdx is an external_link stub, not a moved content page — it redirects to the Workers gradual deployments page
api/webgpu.mdx retains pcx_content_type: configuration, not changed to reference like the other 9 API pages
tutorials/ sidebar order is 9 (not mentioned in original) — same as platform/ (order 9), which means they rely on alphabetical tiebreaking
api/base.mdx and api/container.mdx both have sidebar.order: 1 — potential ordering collision
examples/ has 9 files (7 examples + 1 index + 1 external_link), not just the "unchanged minus alarms-api, testing" described — the original description omitted listing reference-do-name-using-init.mdx, readable-stream.mdx, agents.mdx
observability/ sidebar order is 8 — the original description said "was 7" but the actual previous order was also 7, making the change 7→8 (confirmed correct)
Stale redirect: /durable-objects/what-are-durable-objects/ still points to /durable-objects/concepts/what-are-durable-objects/ (line 585) which itself redirects to /durable-objects/concepts/how-durable-objects-work/ — this is a redirect chain, not a direct redirect

Notes

tutorials/ (order 9) and platform/ (order 9) share the same sidebar order — platform sorts after tutorials alphabetically
api/base.mdx and api/container.mdx both have sidebar.order: 1 — container may need its own order
gradual-deployments.mdx and rest-api.mdx are external_link stubs, not standalone content pages
webgpu.mdx retains pcx_content_type: configuration (not changed to reference like the other API pages)

Stats

94 files changed across the repo
2,215 additions / 1,938 deletions
55 MDX files in the final durable-objects/ tree
Touches: durable-objects, workers, agents, containers, browser-rendering, data-localization, queues, sandbox, reference-architecture, workflows, partials, changelogs, release-notes, glossary, redirects

github-actions · 2026-02-14T17:52:51Z

github-actions · 2026-02-14T17:53:30Z

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
`/public/__redirects`	`@cloudflare/content-engineering`, `@cloudflare/pcx-technical-writing`
`/src/content/changelog/`	`@cloudflare/pm-changelogs`, `@cloudflare/pcx-technical-writing`
`/src/content/docs/agents/`	`@irvinebroque`, `@rita3ko`, `@elithrar`, `@thomasgauvin`, `@threepointone`, `@whoiskatrin`, `@cloudflare/pcx-technical-writing`, `@cloudflare/ai-agents`, `@cloudflare/dev-plat-leads`
`/src/content/docs/browser-rendering/`	`@mchenco`, `@cloudflare/pcx-technical-writing`, `@celso`, `@kathayl`, `@ToriLindsay`
`/src/content/docs/containers/`	`@mikenomitch`, `@th0m`, `@cloudflare/pcx-technical-writing`, `@cloudflare/cloudchamber`
`/src/content/docs/data-localization/`	`@soheiokamoto`, `@angelampcosta`, `@cloudflare/pcx-technical-writing`
`/src/content/docs/durable-objects/`	`@elithrar`, `@vy-ton`, `@joshthoward`, `@oxyjun`, `@lambrospetrou`, `@mikenomitch`, `@cloudflare/pcx-technical-writing`
`/src/content/docs/queues/`	`@elithrar`, `@jonesphillip`, `@harshil1712`, `@mia303`, `@cloudflare/pcx-technical-writing`
`/src/content/docs/reference-architecture/`	`@securitypedant`, `@cloudflare/pcx-technical-writing`
`/src/content/docs/sandbox/`	`@whoiskatrin`, `@ghostwriternr`, `@cloudflare/pcx-technical-writing`, `@cloudflare/ai-agents`
`/src/content/docs/workers/`	`@cloudflare/workers-docs`, `@GregBrimble`, `@irvinebroque`, `@mikenomitch`, `@korinne`, `@WalshyDev`, `@cloudflare/deploy-config`, `@cloudflare/pcx-technical-writing`, `@cloudflare/wrangler`, `@mattietk`, `@cloudflare/dev-plat-leads`
`/src/content/docs/workers/wrangler/`	`@cloudflare/wrangler`, `@irvinebroque`, `@cloudflare/pcx-technical-writing`
`*`	`@cloudflare/pcx-technical-writing`
`/src/content/partials/d1/`	`@elithrar`, `@rozenmd`, `@vy-ton`, `@joshthoward`, `@oxyjun`, `@harshil1712`, `@cloudflare/pcx-technical-writing`
`/src/content/partials/durable-objects/`	`@elithrar`, `@rita3ko`, `@irvinebroque`, `@vy-ton`, `@cloudflare/pcx-technical-writing`
`/src/content/release-notes/durable-objects.yaml`	`@elithrar`, `@vy-ton`, `@joshthoward`, `@oxyjun`, `@cloudflare/pcx-technical-writing`
`/src/content/release-notes/workers.yaml`	`@cloudflare/workers-docs`, `@GregBrimble`, `@WalshyDev`, `@aninibread`, `@cloudflare/deploy-config`, `@cloudflare/pcx-technical-writing`, `@irvinebroque`, `@mikenomitch`, `@mattietk`

…1+2)

…orrect sidebar order

…em, split merged steps

github-actions · 2026-02-14T19:02:39Z

Preview URL: https://2e418549.preview.developers.cloudflare.com
Preview Branch URL: https://diataxis-do-restructure.preview.developers.cloudflare.com

Files with changes (up to 15)

github-actions · 2026-02-14T19:04:06Z

CI run failed: build logs

elithrar · 2026-02-14T21:06:06Z

/bonk fix it

validating links 
Error: 4 [ERROR] ✗ Found 1 invalid link in 1 file.
19:04:04 ▶ workflows/build/rules-of-workflows/
19:04:04   └─ /durable-objects/best-practices/rules-of-durable-objects/ - invalid link

Error: 4 [ERROR] [starlight-links-validator-integration] An unhandled error occurred while running the "astro:build:done" hook
[AstroUserError] Links validation failed.
  Hint:
    See the error report above for more informations.
    
    If you believe this is a bug, please file an issue at https://github.com/HiDeoo/starlight-links-validator/issues/new/choose
  Location:
    /home/runner/work/cloudflare-docs/cloudflare-docs/node_modules/starlight-links-validator/index.ts:78:9
  Stack trace:
    at throwPluginError (/home/runner/work/cloudflare-docs/cloudflare-docs/node_modules/starlight-links-validator/index.ts:78:9)
    at hookFn (file:///home/runner/work/cloudflare-docs/cloudflare-docs/node_modules/astro/dist/integrations/hooks.js:54:21)
    at runHookInternal (file:///home/runner/work/cloudflare-docs/cloudflare-docs/node_modules/astro/dist/integrations/hooks.js:51:11)
    at async AstroBuilder.build (file:///home/runner/work/cloudflare-docs/cloudflare-docs/node_modules/astro/dist/core/build/index.js:164:5)
    at async build (file:///home/runner/work/cloudflare-docs/cloudflare-docs/node_modules/astro/dist/core/build/index.js:45:3)
Error: Process completed with exit code 1.

Co-authored-by: elithrar <elithrar@users.noreply.github.com>

ask-bonk · 2026-02-14T21:07:59Z

Fixed. The link in src/content/docs/workflows/build/rules-of-workflows.mdx:636 was pointing to the old path /durable-objects/best-practices/rules-of-durable-objects/ and is now updated to /durable-objects/concepts/rules-of-durable-objects/.

github run

elithrar · 2026-02-15T16:36:07Z

/bonk update the PR description with the latest changes to this structure.

Highlight any drift in your comment.

ask-bonk · 2026-02-15T16:40:55Z

Updated PR #28345 description with the audited structure. Here is the drift I found between the original description and the actual files on the branch:

rules-of-durable-objects.mdx was refreshed (343 adds / 326 deletes), not "unchanged" as claimed
api/rest-api.mdx is an external_link stub redirecting to the API docs, not a moved content page
how-to/gradual-deployments.mdx is also an external_link stub, not moved content
api/webgpu.mdx kept pcx_content_type: configuration — it was not changed to reference like the other 9 API pages
api/base.mdx and api/container.mdx both have sidebar.order: 1 — ordering collision
tutorials/ and platform/ both have sidebar.order: 9 — relies on alphabetical tiebreaking
examples/ listing was incomplete — omitted reference-do-name-using-init.mdx, readable-stream.mdx, and agents.mdx
Redirect chain: /durable-objects/what-are-durable-objects/ → concepts/what-are-durable-objects/ → concepts/how-durable-objects-work/ (two hops instead of one)

The new PR description includes the full tree with sidebar orders, a redirect table, and all drift items highlighted in their own section.

github run

github-actions bot assigned irvinebroque, rita3ko, thomasgauvin, threepointone and whoiskatrin Feb 14, 2026

github-actions bot assigned celso, kathayl, mchenco, ToriLindsay and mikenomitch Feb 14, 2026

elithrar added 4 commits February 14, 2026 13:43

[Durable Objects] restructure docs around Diátaxis framework (phases …

a7516f9

…1+2)

[Durable Objects] review fixes: TS-first examples, fix broken link, c…

800e605

…orrect sidebar order

[Durable Objects] remove unused imports, add missing compatibility_date

a338001

[Durable Objects] fix Steps component: indent DashButton into list it…

3dd50ef

…em, split merged steps

elithrar force-pushed the diataxis-do-restructure branch from 61c33db to 3dd50ef Compare February 14, 2026 18:43

elithrar added 2 commits February 14, 2026 13:45

[Durable Objects] rename concepts/networking to calling-durable-objects

8981e47

[Durable Objects] rename concepts/storage to storage-and-state

2e41854

Fix broken link in workflows docs

8a2ab3c

Co-authored-by: elithrar <elithrar@users.noreply.github.com>

cloudflare deleted a comment from Trish1980 Feb 16, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Durable Objects] restructure docs around Diátaxis framework#28345

[Durable Objects] restructure docs around Diátaxis framework#28345
elithrar wants to merge 7 commits intoproductionfrom
diataxis-do-restructure

elithrar commented Feb 14, 2026 •

edited by ask-bonk bot

Loading

Uh oh!

github-actions bot commented Feb 14, 2026

Uh oh!

github-actions bot commented Feb 14, 2026

Uh oh!

github-actions bot commented Feb 14, 2026

Uh oh!

github-actions bot commented Feb 14, 2026

Uh oh!

elithrar commented Feb 14, 2026

Uh oh!

ask-bonk bot commented Feb 14, 2026

Uh oh!

elithrar commented Feb 15, 2026

Uh oh!

ask-bonk bot commented Feb 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

Conversation

elithrar commented Feb 14, 2026 • edited by ask-bonk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Structure (Diátaxis framework)

Content movements

Redirects

Drift from original PR description

Notes

Stats

Uh oh!

github-actions bot commented Feb 14, 2026

Redirects

Partials

Uh oh!

github-actions bot commented Feb 14, 2026

Uh oh!

github-actions bot commented Feb 14, 2026

Uh oh!

github-actions bot commented Feb 14, 2026

Uh oh!

elithrar commented Feb 14, 2026

Uh oh!

ask-bonk bot commented Feb 14, 2026

Uh oh!

elithrar commented Feb 15, 2026

Uh oh!

ask-bonk bot commented Feb 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

elithrar commented Feb 14, 2026 •

edited by ask-bonk bot

Loading