docs: Split models page into three use cases#465
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Splits the previously large “models” documentation into three focused pages (core models, inheritance/polymorphism, and vector fields) and updates navigation + cross-links accordingly.
Changes:
- Added a new
Modelsdocs category with “Working with models” as the category landing page. - Moved inheritance/polymorphism and vector fields content into dedicated docs pages.
- Updated inbound links across docs to point to the new locations/anchors.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/06-concepts/22-experimental.md | Updates an inheritance cross-link to the new inheritance/polymorphism doc path. |
| docs/06-concepts/09-logging.md | Updates the duration-format reference link to the new models section anchor. |
| docs/06-concepts/02-models/category.json | Introduces a new “Models” sidebar category and links it to the core models doc. |
| docs/06-concepts/02-models/03-vector-fields.md | New standalone page documenting vector field types and references. |
| docs/06-concepts/02-models/02-inheritance-and-polymorphism.md | New standalone page for inheritance + polymorphism guidance and examples. |
| docs/06-concepts/02-models/01-models.md | Becomes the core “Working with models” page; adds slug and updates internal references to split-out pages. |
| docs/01-get-started/03-working-with-the-database.md | Updates link to the relocated models keywords reference. |
| docs/01-get-started/02-models-and-data.md | Updates link to the relocated “Working with models” doc. |
| docs/01-get-started/01-creating-endpoints.md | Updates link to the relocated serializable model reference. |
Comments suppressed due to low confidence (2)
docs/06-concepts/02-models/01-models.md:25
- The links to the Vector type sections look like they include an extra
models/path segment (e.g../models/vector-fields#vector). Sincevector-fieldsis a sibling doc within the same02-modelsfolder, this likely resolves to a non-existent doc path and will trip the broken-link checks. Update these links to point directly to the sibling doc (e.g.vector-fields#vector,vector-fields#halfvector, etc.).
docs/06-concepts/02-models/01-models.md:554 - These keyword table links use
./models/inheritance-and-polymorphism..., which appears to add an extramodels/segment relative to this doc’s location. The target doc is a sibling (inheritance-and-polymorphism), so this link is likely broken and will fail the docs build’s broken-link validation. Point the links directly at the sibling doc (e.g.inheritance-and-polymorphism#...).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <[email protected]>
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
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.
Problem
The models page has become the largest file in the docs, by far. It includes advanced use cases that make it harder for newcomers to understand.
Solution
Divide the file into three use cases:
The core page is still quite large (500+ lines), but no single topic is large enough to warrant a new page.
Change in menu structure
The files are placed in a new folder, and the core page ("Working with models") loads when the "Working with models" menu category is clicked.
Fixes serverpod/serverpod#4250.