Refactor: Reorganize Documentation Structure #247
Closed
Conversation
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
|
Contributor
Author
|
View your CI Pipeline Execution ↗ for commit 9e6f90f
☁️ Nx Cloud last updated this comment at |
jumski
changed the title
jumski
force-pushed
the
10-08-docs-reorganization
branch
2 times, most recently
from
1fe3434 to
96730b0
Compare
jumski
force-pushed
the
10-08-docs-reorganization
branch
from
96730b0 to
8f7cfb3
Compare
jumski
force-pushed
the
10-08-docs-reorganization
branch
from
8f7cfb3 to
d7d32eb
Compare
jumski
force-pushed
the
10-08-docs-reorganization
branch
from
d7d32eb to
b4d9dda
Compare
jumski
force-pushed
the
10-08-docs-reorganization
branch
from
b4d9dda to
b064b53
Compare
![graphite-app[bot]](https://avatars.githubusercontent.com/in/158384?s=60&v=4){kind=small}
pkgs/website/src/content/docs/get-started/flows/compile-flow.mdx
Outdated
Show resolved
Hide resolved
jumski
force-pushed
the
10-08-docs-reorganization
branch
from
b064b53 to
457fd43
Compare
jumski
force-pushed
the
10-08-docs-reorganization
branch
from
457fd43 to
55d45cc
Compare
jumski
force-pushed
the
10-08-docs-reorganization
branch
from
a02c9ab to
be24e53
Compare
jumski
force-pushed
the
10-08-docs-reorganization
branch
from
be24e53 to
15078a9
Compare
This was referenced Oct 13, 2025
jumski
force-pushed
the
10-08-docs-reorganization
branch
from
15078a9 to
ad80404
Compare
jumski
force-pushed
the
10-08-docs-reorganization
branch
from
ad80404 to
2dd9d0b
Compare
- Moved several 'how-to' pages to 'build' and 'production' sections for clarity - Renamed multiple files to better reflect their content and categorization - Updated navigation links and sidebar topics to match new structure - Removed obsolete edge-worker installation page, replaced with updated references - Standardized redirects and links for improved user flow and consistency
jumski
force-pushed
the
10-08-docs-reorganization
branch
from
2dd9d0b to
9e6f90f
Compare
Contributor
🔍 Preview Deployment: Website✅ Deployment successful! 🔗 Preview URL: https://pr-247.pgflow.pages.dev 📝 Details:
_Last updated: _ |
Contributor
🔍 Preview Deployment: Playground✅ Deployment successful! 🔗 Preview URL: https://pr-247--pgflow-demo.netlify.app 📝 Details:
_Last updated: _ |
This was referenced Oct 18, 2025
Contributor
Merge activity
|
graphite-app bot
pushed a commit
that referenced
this pull request
Oct 18, 2025
## Summary This PR restructures the pgflow documentation to improve navigation and align with the Diátaxis framework. The changes reorganize content into clearer categories and establish comprehensive redirects to maintain backward compatibility. ## Key Changes ### Documentation Reorganization **1. Getting Started Flow** - Split `/getting-started/` into focused sections: - `/get-started/installation/` - Core setup - `/get-started/flows/` - Flow creation, compilation, and execution - `/get-started/background-jobs/` - Worker setup - `/get-started/faq/` - Common questions **2. How-To Guides Split** - Task-oriented guides moved to `/develop/`: - `/develop/authoring/` - Flow creation patterns - `/develop/config-tuning/` - Configuration updates - `/develop/manage/` - Versioning and deletion - Operational guides moved to `/operate/`: - `/operate/deploy/` - Deployment strategies - `/operate/observe/` - Monitoring and observability - `/operate/maintain/` - Updates, pruning, connections **3. Concepts Restructured** - `/concepts/overview/` - Core concepts and introduction - `/concepts/architecture/` - How pgflow works - `/concepts/flows/` - DSL and flow-specific concepts **4. Reference Consolidation** - `/reference/configuration/` - Configuration reference - `/reference/apis/` - API documentation - `/reference/queue-worker/` - Worker internals **5. Comparisons** - Renamed `/vs/` to `/comparisons/` for clarity ### Redirects Added 100+ redirect rules covering all moved pages, including: - Legacy paths from previous reorganizations - Edge worker documentation moves - How-to guide splits - Concept restructuring - Configuration moves All redirects maintain trailing slashes per site configuration. ### Navigation Updates Updated Starlight sidebar configuration to reflect new structure with clear categories: - Get Started (rocket icon) - Develop (puzzle icon) - Operate (setting icon) - Concepts (information icon) - Reference (document icon) - Tutorials (open-book icon) - Comparisons (approve-check icon) ## Backward Compatibility All existing URLs redirect to their new locations. External links and bookmarks will continue to work. ## Testing - Verified all internal links resolve correctly - Confirmed redirects work as expected - Validated sidebar navigation structure
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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
This PR restructures the pgflow documentation to improve navigation and align with the Diátaxis framework. The changes reorganize content into clearer categories and establish comprehensive redirects to maintain backward compatibility.
Key Changes
Documentation Reorganization
1. Getting Started Flow
/getting-started/into focused sections:/get-started/installation/- Core setup/get-started/flows/- Flow creation, compilation, and execution/get-started/background-jobs/- Worker setup/get-started/faq/- Common questions2. How-To Guides Split
/develop/:/develop/authoring/- Flow creation patterns/develop/config-tuning/- Configuration updates/develop/manage/- Versioning and deletion/operate/:/operate/deploy/- Deployment strategies/operate/observe/- Monitoring and observability/operate/maintain/- Updates, pruning, connections3. Concepts Restructured
/concepts/overview/- Core concepts and introduction/concepts/architecture/- How pgflow works/concepts/flows/- DSL and flow-specific concepts4. Reference Consolidation
/reference/configuration/- Configuration reference/reference/apis/- API documentation/reference/queue-worker/- Worker internals5. Comparisons
/vs/to/comparisons/for clarityRedirects
Added 100+ redirect rules covering all moved pages, including:
All redirects maintain trailing slashes per site configuration.
Navigation Updates
Updated Starlight sidebar configuration to reflect new structure with clear categories:
Backward Compatibility
All existing URLs redirect to their new locations. External links and bookmarks will continue to work.
Testing