docs: documentation overhaul - #728
Merged
Merged
Conversation
|
Warning Review limit reachedNext included review available in 41 minutes. View limit detailsLimit details: You’ve used the included review currently available. You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Review configuration: ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Advanced Run ID: 📒 Files selected for processing (1)
📝 SummarySummary by CodeRabbit
WalkthroughThe pull request restructures the documentation hierarchy, updates installation and tutorial examples, adds resolver and stitching guidance, and revises MkDocs navigation and assets. No functional library code changes were made. ChangesDocumentation publishing and navigation
Installation and tutorial content
Type system reference
General reference updates
Merge Risk: 🔵 Low · up to The documentation change carries a minor publishing risk: dependency placeholders may display as undefined when the site version element is unavailable. It is mergeable with a bounded follow-up to guard that case. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #728 +/- ##
=======================================
Coverage 84.12% 84.12%
=======================================
Files 150 150
Lines 4931 4931
Branches 856 856
=======================================
Hits 4148 4148
Misses 486 486
Partials 297 297 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Advanced
Run ID: fab43911-44fb-4988-8e5b-317efe8aafe1
📒 Files selected for processing (18)
docs/content/Examples/index.mddocs/content/Installation/index.mddocs/content/Plugins/ktor.mddocs/content/Reference/Type System/enums.mddocs/content/Reference/Type System/input-objects.mddocs/content/Reference/Type System/objects-and-interfaces.mddocs/content/Reference/Type System/overview.mddocs/content/Reference/Type System/scalars.mddocs/content/Reference/Type System/unions.mddocs/content/Reference/configuration.mddocs/content/Reference/deprecation.mddocs/content/Reference/operations.mddocs/content/Reference/resolver.mddocs/content/Reference/stitching.mddocs/content/Tutorials/ktor.mddocs/content/Tutorials/starwars.mddocs/content/assets/replace_maven_version.jsdocs/mkdocs.yml
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
All reported issues were addressed across 18 files
Architecture diagram
sequenceDiagram
participant Author as Documentation Author
participant Markdown as Markdown Pages
participant MkDocs as MkDocs Configuration
participant Build as MkDocs Build Pipeline
participant Browser as Documentation Browser
participant Maven as Material Version Metadata
participant IDE as IDE Markdown Preview
Note over Author,IDE: Documentation presentation and version-substitution flow
Author->>Markdown: Write pages with level 1 titles, structured headings, examples, and admonitions
Author->>MkDocs: Configure navigation, markdown extensions, and assets
MkDocs->>Build: Load nav paths and enable admonition extension
MkDocs->>Build: Register replace_maven_version.js as extra JavaScript
Markdown->>Build: Provide page content and ${KGraphQLVersion} placeholders
Build->>Build: Render Markdown, headings, navigation, code blocks, and admonitions
Build-->>Browser: Serve generated HTML with navigation and version metadata
Browser->>Maven: Read latest release tag from rendered version element
Maven-->>Browser: Return latest KGraphQL version text
Browser->>Browser: Replace all ${KGraphQLVersion} placeholders in document HTML
Browser-->>Browser: Display dependency snippets with resolved version
alt Version metadata is unavailable
Browser->>Browser: Leave ${KGraphQLVersion} placeholders unchanged
end
opt Standalone page preview
IDE->>Markdown: Open a single Markdown page
Markdown-->>IDE: Render level 1 title and heading hierarchy directly
end
Note over MkDocs,Browser: Navigation labels are derived from page titles and configured paths
Note over Markdown,Build: Content structure is shared by generated documentation and standalone previews
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
Bencher Report
mervyn-mccreight
previously approved these changes
Sep 10, 2026
stuebingerb
force-pushed
the
docs/docs-overhaul
branch
from
September 10, 2026 15:55
cce0880 to
625c1ea
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Advanced
Run ID: 866cb596-ebaa-42b8-b608-e2f66f870c2d
📒 Files selected for processing (5)
docs/content/Reference/Type System/overview.mddocs/content/Reference/Type System/unions.mddocs/content/Reference/errorHandling.mddocs/content/Reference/stitching.mddocs/content/assets/replace_maven_version.js
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/content/Reference/Type System/overview.md
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.
There was a problem hiding this comment.
All reported issues were addressed across 19 files
Architecture diagram
sequenceDiagram
participant Author as Documentation Author
participant Source as Markdown Content
participant Config as mkdocs.yml
participant MkDocs as MkDocs Build
participant Theme as Material for MkDocs
participant Browser as Reader Browser
participant Script as Version Replacement Script
Note over Author,Theme: Documentation publishing and rendering flow
Author->>Source: Write Markdown pages with level 1 titles,\nheadings, examples, links, and admonitions
Author->>Config: Define navigation paths,\nMarkdown extensions, theme assets, and plugins
MkDocs->>Config: Load site configuration
MkDocs->>Source: Read pages referenced by navigation
Source-->>MkDocs: Markdown content with ${KGraphQLVersion}
MkDocs->>MkDocs: Convert Markdown to HTML
MkDocs->>MkDocs: Apply heading hierarchy and admonition extension
MkDocs->>Theme: Render HTML using page headings and navigation paths
Theme-->>MkDocs: Generated documentation site
MkDocs-->>Browser: Serve generated HTML, CSS, and JavaScript
Browser->>Script: Load extra_javascript assets
Script->>Browser: Read latest version from Material theme metadata
Script->>Browser: Find text nodes containing ${KGraphQLVersion}
alt Version metadata is available
Script->>Browser: Replace placeholders with latest release tag
else Version metadata is unavailable
Script-->>Browser: Leave placeholders unchanged
end
Browser->>Browser: Render navigation, headings,\ncode examples, and admonitions
Browser-->>Reader: Display documentation page
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
### Titles
Some pages had no title, some had it set via meta data, some had it
set as level 1 markdown header. And in the end, everything was anyway
overridden by the title set in `mkdocs.yml`.
This consolidates everything to the level 1 markdown header because
that keeps the title closer to the content, and is also rendered
without mkdocs, e.g. in the IDE preview of a single page.
Explicit titles in the navigation configuration are removed to avoid
duplication.
### Weight
Weight doesn't seem to have an effect with explicit navigation
configuration and was removed.
### Uppercase/lowercase
We consolidate all uses of `ktor/Ktor` to `Ktor` for the official name.
In addition, all headings now use title case.
### Missing Sub Headings
Some pages missed an additional "overview" heading as first item, and
some pages missed sub headings at all. Both have been added for better
structure, and a more consistent table of contents.
### Correct Heading Levels
Some pages had level 1 and level 3 headings and are now using level 1
and level 2 instead for proper hierarchies.
### Latest Maven Version
Adds a small snippet to automatically replace `${KGraphQLVersion}`
with the latest release tag.
### Admonitions
Use admonitions to make experimental warnings more visible.
### Missing Content
Add missing content in a few places.
stuebingerb
force-pushed
the
docs/docs-overhaul
branch
from
September 10, 2026 16:13
625c1ea to
b13383b
Compare
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
2 participants
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.
Titles
Some pages had no title, some had it set via meta data, some had it set as level 1 markdown header. And in the end, everything was anyway overridden by the title set in
mkdocs.yml.This consolidates everything to the level 1 markdown header because that keeps the title closer to the content, and is also rendered without mkdocs, e.g. in the IDE preview of a single page. Explicit titles in the navigation configuration are removed to avoid duplication.
Weight
Weight doesn't seem to have an effect with explicit navigation configuration and was removed.
Uppercase/lowercase
We consolidate all uses of
ktor/KtortoKtorfor the official name. In addition, all headings now use title case.Missing Sub Headings
Some pages missed an additional "overview" heading as first item, and some pages missed sub headings at all. Both have been added for better structure, and a more consistent table of contents.
Correct Heading Levels
Some pages had level 1 and level 3 headings and are now using level 1 and level 2 instead for proper hierarchies.
Latest Maven Version
Adds a small snippet to automatically replace
${KGraphQLVersion}with the latest release tag.Admonitions
Use admonitions to make experimental warnings more visible.
Missing Content
Add missing content in a few places.