docs(api): enrich 3 API endpoint pages to fix 'crawled - currently not indexed' - #155
Merged
Merged
Conversation
…t indexed" Prototype for clearing the thin-content indexing problem on docs.turbodocx.com. GSC shows 42 docs pages stuck in "Crawled - currently not indexed"; per Search Engine Journal/Land that status is a content-quality signal (thin/templated pages). These API reference pages rendered ~80 words of unique content. Enriches delete-template, get-templates-and-folders, and upload-template-with-optional-default-values with: a real meta description, an intro + "when to use", a runnable curl example, an example response, a common-errors table, and related-endpoint links. Validated: compiles under MDX v3 (Docusaurus 3.10 engine). Note: these .api.mdx files are generated by docusaurus-plugin-openapi-docs and are currently STALE (spec descriptions were enriched 2026-05-17 but pages last generated 2026-05-06). Sustainable rollout should move rich content into the OpenAPI spec descriptions and fix the regen pipeline (config outputDir 'docs/api/turbodocx' does not match the served 'docs/API/'). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TfRHAUz2HTtpSJ1XxYYQa1
…havior
Replaces the inferred examples from the previous commit with responses and
error codes verified against RapidDocxBackend handlers and the TS SDK:
- Standard response envelope is { data: { results, [totalRecords] } };
errors are { message, error, data: { explanation, context } }.
- delete-template: returns 200 { data: {} }; soft delete, idempotent (no 404);
errors 401/403 are status-only, 400 on bad UUID. Dropped the invented 404.
- get-templates-and-folders: real item fields, { data: { results, totalRecords } };
limit default 9 + offset paging, plus query/selectedTags/column0/order0;
showTags defaults to true. Dropped invented "templateItems"/"total"/403.
- upload-template: returns 201 { data: { results: { template } } } with the
real Template row; errors are plan-limit 400 (uses "type"), improper-file 400,
storage 503. Dropped the invented 413.
TS SDK exposes no document-template methods (confirmed), so no SDK snippets
were added. Auth is Authorization: Bearer <apiKey> + x-rapiddocx-org-id.
All three compile under MDX v3.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TfRHAUz2HTtpSJ1XxYYQa1
Verified against RapidDocxBackend handlers/schemas:
- delete-template: locked template returns 423 { error, message, data:{locked,lockedBy,lockedOn} }, not a 403 empty body.
- upload-template: name and variables are REQUIRED for POST (were shown optional); clarified "optional default values" means per-variable defaults.
- get-templates: createdBy is a user UUID (not a display name); fileType is the full MIME type (not "docx").
- get-templates: intro corrected -- default returns only root-level items; type=template enumerates across folders.
- all three: Joi/celebrate validation 400s use { message, type:"ValidationError", data:{errors} }, not the { message, error, data:{explanation,context} } envelope; upload now separates schema-validation vs file/storage/plan-limit error shapes.
All three recompile under MDX v3.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TfRHAUz2HTtpSJ1XxYYQa1
nicolasiscoding
marked this pull request as ready for review
September 7, 2026 19:43
Member
Author
|
approved |
5 tasks
nicolasiscoding
pushed a commit
that referenced
this pull request
Sep 7, 2026
Brings the delete-template / get-templates-and-folders / upload-template enrichment (PR #155) into the develop integration branch. No conflicts; disjoint files from develop's in-flight docs work. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TfRHAUz2HTtpSJ1XxYYQa1
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
1 participant
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.
Closes #156
Why
GSC shows 42
docs.turbodocx.compages stuck in Crawled – currently not indexed, concentrated in the auto-generated API reference. Per Search Engine Journal/Land, that status is a content-quality signal (thin/templated pages); these API pages rendered ~80 words of unique content.This is a 3-endpoint prototype to validate the fix before scaling to the other ~40: enrich the page, deploy, manually Request Indexing in GSC, and confirm it moves to Indexed.
What
Enriches
delete-template,get-templates-and-folders, andupload-template-with-optional-default-valueswith a real meta description, intro + "when to use", a runnable curl example, an accurate example response, a common-errors table, and related-endpoint links.Accuracy: all responses and error codes are verified against the actual
RapidDocxBackendhandlers (not inferred):{ data: { results, [totalRecords] } }; errors{ message, error, data: { explanation, context } }.200 { data: {} }(soft, idempotent, no 404); list → real item fields +limit(9)/offsetpaging,showTagsdefault true; upload →201 { data: { results: { template } } }, errors plan-limit 400 / improper-file 400 / storage 503.All 3 compile under MDX v3 (Docusaurus 3.10 engine).
Note for reviewers / follow-up
These
.api.mdxfiles are generated bydocusaurus-plugin-openapi-docsand are currently stale (spec descriptions were enriched after the pages were last generated). Sustainable rollout should move rich content into the OpenAPI spec and fix the regen pipeline (configoutputDirdocs/api/turbodocxdoes not match the serveddocs/API/).🤖 Generated with Claude Code