Reorganize Strapi/Redis/Medusa/Algolia documentation #473
Conversation
WalkthroughThis PR restructures documentation for multiple integrations (Redis cache, Contentful, Strapi, Medusa.js, SurveyJS, Algolia, Zendesk) by organizing single-file docs into modular guides with category configs, features, setup, and usage sections. Component prop structures are updated, theming docs are reorganized, and integration links are refreshed. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25–35 minutes
Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches❌ Failed checks (2 warnings)
✅ Passed checks (1 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (12)
apps/docs/src/css/custom.css (1)
1441-1517: Table styling implementation looks solid.The comprehensive markdown table styling adds proper visual hierarchy with header styling, hover effects, rounded corners, and consistent padding. The use of
border-collapse: separatewithborder-spacing: 0andoverflow: hiddenis a standard approach for achieving border-radius on tables.Minor note: There's a slight inconsistency in cell border opacity (0.15 on line 1455 vs. 0.1 on lines 1505–1506), which may be intentional for visual differentiation but could be documented or unified for clarity.
apps/docs/docs/integrations/cms/strapi/how-to-setup.md (1)
125-127: Consider more concise phrasing.The phrase "in order to" on Line 126 can be shortened to "to" for improved readability: "This command requires that the
CMS_STRAPI_BASE_URLenvironment variable is set to retrieve..."This is a minor style improvement and not blocking.
apps/docs/docs/integrations/cms/strapi/graphql.md (1)
21-23: Consider more concise phrasing.The phrase "in order to" on Line 22 can be shortened to "to" for improved readability: "This command requires that the
CMS_STRAPI_BASE_URLenvironment variable is set to retrieve the GraphQL schema..."This is a minor style improvement for consistency with other docs and not blocking.
apps/docs/docs/integrations/tickets/zendesk/features.md (1)
69-78: Avoid duplicating the “Data Normalization” sectionYou currently describe data normalization twice: a brief list under
### 3. Data Normalizationand then a full## Data Normalizationsection with Field/Status/Topic details. Consider either removing the earlier brief bullets or renaming it (e.g., “Data Normalization overview”) so there’s a single, clearly structured normalization section.Also applies to: 98-148
apps/docs/docs/integrations/tickets/zendesk/usage.md (2)
156-160: Tighten fenced code formatting and minor wording
- For the Authorization header code block, add a language (e.g.
text) to satisfy MD040 and keep linting happy:-``` +```text Authorization: Bearer {your_auth_token}- In the “Filter by Type/Priority” section, consider “high‑priority tickets” instead of “high priority tickets” for slightly smoother phrasing. Also applies to: 186-203 --- `263-271`: **Clarify “Ticket Not Found” HTTP behavior** This section documents `200 OK` with an `undefined` body for not-found/unauthorized tickets. Since `undefined` isn’t valid JSON, it would help to either (a) show the actual serialized response shape (`null`, empty object, etc.) or (b) explicitly note that “undefined” refers to the server-side return value, while the HTTP response is still valid JSON. Otherwise API consumers may be unsure what to expect on the wire. </blockquote></details> <details> <summary>apps/docs/docs/integrations/tickets/zendesk/how-to-setup.md (2)</summary><blockquote> `7-7`: **Fix hyphenation in user-facing documentation.** Use "Open Self-Service" instead of "Open Self Service" for consistency with proper compound adjective formatting. Apply this change: ```diff -This guide will walk you through setting up the Zendesk integration in your Open Self Service application. +This guide will walk you through setting up the Zendesk integration in your Open Self-Service application.Note: This same hyphenation issue appears in the overview.md file (line 7, 25) and in the Algolia how-to-setup.md file (line 7).
103-110: Module dependencies section is clear but could be slightly more specific.The section correctly identifies that the Users module is required, but consider clarifying whether it must be configured before or as part of the Zendesk integration setup, and whether there are any specific configuration requirements beyond "properly set up."
apps/docs/docs/integrations/tickets/zendesk/overview.md (1)
7-7: Fix hyphenation in compound adjectives.Two instances of "Open Self Service" should use hyphenation: "Open Self-Service".
Apply these changes:
-This integration provides the integration with [Zendesk Ticketing module](https://developer.zendesk.com/api-reference/ticketing/introduction/), allowing users to view and manage their support tickets within your application. +This integration provides the integration with [Zendesk Ticketing module](https://developer.zendesk.com/api-reference/ticketing/introduction/), allowing users to view and manage their support tickets within your Open Self-Service application.And:
-This integration connects your Open Self Service application with Zendesk, enabling users to view and manage their support tickets directly within your application. +This integration connects your Open Self-Service application with Zendesk, enabling users to view and manage their support tickets directly within your application.Also applies to: 25-25
apps/docs/docs/integrations/search/algolia/how-to-setup.md (1)
7-7: Fix hyphenation in user-facing documentation (same issue as other integration docs).Use "Open Self-Service" instead of "Open Self Service" for consistency.
Apply this change:
-This guide will walk you through setting up the Algolia integration in your Open Self Service application. +This guide will walk you through setting up the Algolia integration in your Open Self-Service application.apps/docs/src/pages/product/starters.tsx (1)
174-184: Customer starter links look good; consider tab behavior for internal DocsThe customer starter follows the same structured link pattern and looks consistent. If you don’t explicitly want internal docs (
/docs/app-starters/o2s/overview) to open in a new tab, you could droptarget: '_blank'for that one (and the corresponding DXP docs link) to keep navigation more standard for internal routes.apps/docs/src/components/StarterInfoSection/index.tsx (1)
53-79: CTA/CLI layout is clear; consider tightening spacing on wider screensThe grouping of
CopyCommandButtonwith primary/secondary CTAs reads well. If you want to avoid extra vertical spacing between buttons onsm+screens, you could override the vertical spacing there:- <div className={clsx('sm:flex gap-2 space-y-4 w-full')}> + <div className={clsx('sm:flex gap-2 space-y-4 sm:space-y-0 w-full')}>
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (52)
README.md(2 hunks)apps/docs/docs/integrations/cache/redis.md(0 hunks)apps/docs/docs/integrations/cache/redis/_category_.json(1 hunks)apps/docs/docs/integrations/cache/redis/features.md(1 hunks)apps/docs/docs/integrations/cache/redis/how-to-setup.md(1 hunks)apps/docs/docs/integrations/cache/redis/overview.md(1 hunks)apps/docs/docs/integrations/cache/redis/usage.md(1 hunks)apps/docs/docs/integrations/cms/contentful/blocks.md(1 hunks)apps/docs/docs/integrations/cms/contentful/content-model.md(1 hunks)apps/docs/docs/integrations/cms/contentful/features.md(9 hunks)apps/docs/docs/integrations/cms/contentful/graphql.md(0 hunks)apps/docs/docs/integrations/cms/contentful/how-to-setup.md(1 hunks)apps/docs/docs/integrations/cms/contentful/overview.md(1 hunks)apps/docs/docs/integrations/cms/strapi/blocks.md(1 hunks)apps/docs/docs/integrations/cms/strapi/content-model.md(1 hunks)apps/docs/docs/integrations/cms/strapi/features.md(1 hunks)apps/docs/docs/integrations/cms/strapi/getting-started.md(0 hunks)apps/docs/docs/integrations/cms/strapi/graphql.md(1 hunks)apps/docs/docs/integrations/cms/strapi/how-to-setup.md(1 hunks)apps/docs/docs/integrations/cms/strapi/overview.md(1 hunks)apps/docs/docs/integrations/commerce/medusa-js.md(0 hunks)apps/docs/docs/integrations/commerce/medusa-js/_category_.json(1 hunks)apps/docs/docs/integrations/commerce/medusa-js/features.md(1 hunks)apps/docs/docs/integrations/commerce/medusa-js/overview.md(1 hunks)apps/docs/docs/integrations/forms/surveyjs.md(0 hunks)apps/docs/docs/integrations/forms/surveyjs/_category_.json(1 hunks)apps/docs/docs/integrations/forms/surveyjs/features.md(1 hunks)apps/docs/docs/integrations/forms/surveyjs/how-to-setup.md(1 hunks)apps/docs/docs/integrations/forms/surveyjs/overview.md(1 hunks)apps/docs/docs/integrations/forms/surveyjs/usage.md(1 hunks)apps/docs/docs/integrations/overview.md(1 hunks)apps/docs/docs/integrations/search/algolia.md(0 hunks)apps/docs/docs/integrations/search/algolia/_category_.json(1 hunks)apps/docs/docs/integrations/search/algolia/features.md(1 hunks)apps/docs/docs/integrations/search/algolia/how-to-setup.md(1 hunks)apps/docs/docs/integrations/search/algolia/overview.md(1 hunks)apps/docs/docs/integrations/search/algolia/usage.md(1 hunks)apps/docs/docs/integrations/tickets/zendesk/features.md(1 hunks)apps/docs/docs/integrations/tickets/zendesk/how-to-setup.md(1 hunks)apps/docs/docs/integrations/tickets/zendesk/overview.md(1 hunks)apps/docs/docs/integrations/tickets/zendesk/usage.md(1 hunks)apps/docs/docs/main-components/ui-library/index.md(1 hunks)apps/docs/docs/main-components/ui-library/theming.md(0 hunks)apps/docs/docs/main-components/ui-library/theming/_category_.json(1 hunks)apps/docs/docs/main-components/ui-library/theming/cms-configuration.md(1 hunks)apps/docs/docs/main-components/ui-library/theming/css-themes.md(1 hunks)apps/docs/docs/main-components/ui-library/theming/index.md(1 hunks)apps/docs/src/components/HeroBannerSection/index.tsx(4 hunks)apps/docs/src/components/StarterInfoSection/index.tsx(4 hunks)apps/docs/src/css/custom.css(1 hunks)apps/docs/src/pages/product/integrations.tsx(1 hunks)apps/docs/src/pages/product/starters.tsx(2 hunks)
💤 Files with no reviewable changes (7)
- apps/docs/docs/integrations/commerce/medusa-js.md
- apps/docs/docs/integrations/forms/surveyjs.md
- apps/docs/docs/integrations/cms/strapi/getting-started.md
- apps/docs/docs/main-components/ui-library/theming.md
- apps/docs/docs/integrations/cms/contentful/graphql.md
- apps/docs/docs/integrations/cache/redis.md
- apps/docs/docs/integrations/search/algolia.md
🧰 Additional context used
🧠 Learnings (4)
📚 Learning: 2025-12-03T12:34:20.707Z
Learnt from: marcinkrasowski
Repo: o2sdev/openselfservice PR: 419
File: apps/frontend/package.json:52-52
Timestamp: 2025-12-03T12:34:20.707Z
Learning: In the openselfservice repository, the application does not use Next.js cache components (use cache/cacheComponents), so next-intl compatibility limitations related to those experimental features are not a concern.
Applied to files:
apps/docs/docs/integrations/cache/redis/features.mdapps/docs/docs/integrations/cms/contentful/overview.md
📚 Learning: 2025-12-03T14:01:47.549Z
Learnt from: marcinkrasowski
Repo: o2sdev/openselfservice PR: 419
File: packages/blocks/quick-links/package.json:51-51
Timestamp: 2025-12-03T14:01:47.549Z
Learning: In the openselfservice repository, next-intl 4.1.0 (and the version ^4.1.0 used in peerDependencies) works correctly with Next.js 16, despite general community concerns about partial compatibility.
Applied to files:
apps/docs/docs/integrations/cms/contentful/overview.md
📚 Learning: 2025-12-03T12:34:20.707Z
Learnt from: marcinkrasowski
Repo: o2sdev/openselfservice PR: 419
File: apps/frontend/package.json:52-52
Timestamp: 2025-12-03T12:34:20.707Z
Learning: In the openselfservice repository, next-auth v5.0.0-beta.30 supports Next.js 16 through its peerDependencies range: "^14.0.0-0 || ^15.0.0 || ^16.0.0".
Applied to files:
apps/docs/docs/integrations/cms/contentful/overview.md
📚 Learning: 2025-11-28T14:07:04.474Z
Learnt from: marcinkrasowski
Repo: o2sdev/openselfservice PR: 411
File: packages/blocks/product-list/src/frontend/ProductList.client.stories.tsx:15-18
Timestamp: 2025-11-28T14:07:04.474Z
Learning: Mock JWT tokens with placeholder data (e.g., Jane Doe, Acme Corporation) used in Storybook story files (.stories.tsx) for demo/test purposes are acceptable and do not need to be replaced with non-JWT placeholders.
Applied to files:
apps/docs/docs/integrations/cms/contentful/blocks.md
🧬 Code graph analysis (1)
apps/docs/src/components/StarterInfoSection/index.tsx (1)
apps/docs/src/components/CopyCommandButton/index.tsx (1)
CopyCommandButton(11-45)
🪛 LanguageTool
apps/docs/docs/integrations/search/algolia/usage.md
[style] ~327-~327: This phrase is redundant. Consider writing “details”.
Context: ... Solution: Check the error logs for specific details about the API error. ## Best practices...
(SPECIFIC_DETAILS)
apps/docs/docs/integrations/cms/strapi/how-to-setup.md
[grammar] ~97-~97: Use a hyphen to join words.
Context: ...s that are compatible with the Open Self Service framework, such as: - Page conte...
(QB_NEW_EN_HYPHEN)
[style] ~126-~126: Consider a more concise word here.
Context: ...I_BASE_URL` environment variable is set in order to retrieve the GraphQL schema from Strapi...
(IN_ORDER_TO_PREMIUM)
apps/docs/docs/integrations/search/algolia/how-to-setup.md
[grammar] ~7-~7: Use a hyphen to join words.
Context: ...he Algolia integration in your Open Self Service application. ## Install The fi...
(QB_NEW_EN_HYPHEN)
apps/docs/docs/integrations/tickets/zendesk/how-to-setup.md
[grammar] ~7-~7: Use a hyphen to join words.
Context: ...he Zendesk integration in your Open Self Service application. ## Install The fi...
(QB_NEW_EN_HYPHEN)
apps/docs/docs/integrations/forms/surveyjs/how-to-setup.md
[style] ~87-~87: To form a complete sentence, be sure to include a subject or ‘there’.
Context: ...of roles required to submit the survey. Can be empty array [] for public surveys ...
(MISSING_IT_THERE)
apps/docs/docs/integrations/cms/strapi/graphql.md
[style] ~22-~22: Consider a more concise word here.
Context: ...I_BASE_URL` environment variable is set in order to retrieve the GraphQL schema from Strapi...
(IN_ORDER_TO_PREMIUM)
apps/docs/docs/integrations/tickets/zendesk/usage.md
[grammar] ~200-~200: Use a hyphen to join words.
Context: ...` ### Filter by Type/Priority Get high priority tickets: ```bash GET /tickets?...
(QB_NEW_EN_HYPHEN)
apps/docs/docs/integrations/cms/contentful/how-to-setup.md
[grammar] ~101-~101: Use a hyphen to join words.
Context: ...s that are compatible with the Open Self Service framework, such as: - Page conte...
(QB_NEW_EN_HYPHEN)
apps/docs/docs/integrations/tickets/zendesk/overview.md
[grammar] ~25-~25: Use a hyphen to join words.
Context: ...This integration connects your Open Self Service application with Zendesk, enabli...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.18.1)
apps/docs/docs/integrations/cache/redis/features.md
46-46: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
apps/docs/docs/integrations/tickets/zendesk/usage.md
158-158: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
apps/docs/docs/integrations/cache/redis/how-to-setup.md
106-106: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
apps/docs/docs/integrations/commerce/medusa-js/overview.md
121-121: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: deploy-preview
🔇 Additional comments (70)
apps/docs/src/css/custom.css (1)
1481-1489: Verify the nearly-invisible table row border at line 1483.The
border-bottom: 1px solid rgba(255, 255, 255, 0.01)uses 0.01 opacity, which is essentially imperceptible. This may be unintentional or a fallback that serves no visual purpose. Consider either removing it or increasing the opacity to match the rest of the table borders (e.g.,0.15).apps/docs/docs/integrations/commerce/medusa-js/overview.md (1)
13-73: Well-structured installation and configuration documentation.The installation, configuration, and environment setup sections are clear and comprehensive. The step-by-step guidance with code examples makes it straightforward for developers to implement the integration. The references to related documentation and external resources are helpful.
apps/docs/docs/integrations/commerce/medusa-js/_category_.json (1)
1-9: Category descriptor is well-formed.The JSON structure correctly configures the Medusa.js documentation category with appropriate label and positioning. The link properly references the overview documentation.
apps/docs/docs/integrations/commerce/medusa-js/features.md (2)
11-24: Comprehensive feature matrix with clear status indicators.The feature overview table effectively communicates what is supported and what is not, with helpful notes linking to plugin requirements and detailed sections. The explicit marking of "Purchase/Activation" as not implemented sets proper expectations.
28-156: Detailed feature documentation is well-organized and thorough.Each feature section provides sufficient context for developers to understand capabilities, use cases, and requirements (including plugin dependencies). The structure with descriptive headings, bullet points, and cross-references makes navigation easy. Links to external resources and the plugin repository are appropriate and helpful.
apps/docs/docs/integrations/cache/redis/_category_.json (1)
1-8: Proper Docusaurus category configuration.The category structure correctly defines the Redis integration category with appropriate positioning and linking to the overview document. The configuration follows Docusaurus standards.
apps/docs/docs/integrations/cache/redis/overview.md (1)
1-36: Well-structured overview with clear navigation.The overview document effectively introduces the Redis integration, provides a comprehensive environment variables reference, and establishes clear navigation paths to related documentation sections. The cross-references and quick-start guidance set up the user journey well.
apps/docs/docs/integrations/cache/redis/how-to-setup.md (1)
1-123: Comprehensive setup guide with strong step-by-step structure.The setup documentation covers installation, multiple deployment scenarios (Docker, local, production), configuration steps, environment variable setup with recommendations, and verification/troubleshooting. The guide clearly maps which files to update and provides context for why each change is needed.
apps/docs/docs/integrations/cache/redis/usage.md (1)
1-108: Excellent usage documentation with comprehensive examples.The usage guide progresses logically from basic injection through common patterns (cache-aside), specialized approaches (RxJS for CMS), key naming conventions, serialization techniques, invalidation strategies, and debugging. Code examples are clear, properly labeled, and demonstrate both simple and advanced scenarios including edge cases like circular references.
apps/docs/docs/integrations/cache/redis/features.md (1)
1-61: Clear feature documentation with transparent limitations.The features document effectively communicates capabilities via a status table, provides the interface contract, explains operational behaviors (TTL management, connection handling), documents CMS integration patterns, and honestly lists limitations. This transparency helps users make informed decisions about the integration.
apps/docs/docs/integrations/cms/contentful/content-model.md (1)
2-2: Sidebar position update aligns with documentation reorganization.The metadata change reflects the broader documentation restructuring for Contentful CMS integration. Content and formatting are correct.
apps/docs/docs/integrations/cms/contentful/overview.md (2)
7-16: Clear navigation structure with helpful cross-references.The "In this section" guide provides excellent entry points to related documentation. Cross-references align well with companion files (how-to-setup, features, content-model, graphql, live-preview).
26-42: Environment variables table is comprehensive and user-friendly.Good organization with clear descriptions of required vs. optional variables and guidance on obtaining values from Contentful settings.
apps/docs/docs/integrations/cms/contentful/how-to-setup.md (3)
9-19: Clear installation instructions with workspace scope.The npm command properly specifies workspace dependencies, ensuring all necessary packages are installed in the correct locations.
21-73: Configuration section uses effective before/after pattern.Code examples are complete, properly formatted, and show exactly what needs to change. Step numbering and explanations make the process clear for users.
97-110: Content model import section provides helpful context.Good balance between explanation and external reference; users understand what they're importing and why before being directed to the resource repository.
apps/docs/docs/integrations/cms/contentful/blocks.md (3)
2-11: Improved documentation structure with clearer focus.The sidebar position update (100 → 250) aligns with documentation reorganization. The revised heading ("Supported blocks") is more descriptive, and the new introductory bullets about Live Preview metadata provide essential context for developers.
17-43: Implementation status table is well-organized and comprehensive.Clear grouping with implemented blocks listed first, followed by not-implemented blocks. New entries (quick-links, ticket-list) are properly categorized. Table format is easy to scan and maintain.
45-65: Mocked blocks section is expanded with helpful context.The introductory sentence clarifies the purpose of mocked blocks for development/testing. Comprehensive list aids developers in understanding which blocks return static data.
apps/docs/docs/integrations/cms/contentful/features.md (3)
11-29: Feature overview table is well-organized with clear status indicators and anchor navigation.Status indicators (✅,
⚠️ , ❌) are intuitive. Anchor links enable both internal document navigation and external references. Notes column provides helpful context at a glance.
31-158: Detailed feature sections are comprehensive and well-structured.Each section follows a consistent pattern with anchor IDs, clear descriptions, and relevant cross-references. Technical details are appropriately balanced with practical guidance. Partial support (Permissions/Roles) and unsupported features (Live updates) are clearly documented with explanations.
79-87: Themes/Layouts section clearly describes available templates.Good explanation of OneColumnTemplate and TwoColumnTemplate with slot descriptions. Note about extensibility is helpful for future development.
apps/docs/src/components/HeroBannerSection/index.tsx (2)
102-102: Excellent responsive design improvement!The change from
w-1/2tosm:w-1/2ensures buttons are full-width on mobile devices (better tap targets and readability) while maintaining the side-by-side layout on larger screens. This aligns well with the parent container'ssm:flexbehavior and follows mobile-first responsive design principles.Also applies to: 114-114, 129-129
151-151: Good cleanup of redundant transform-origin class.Simplifying to just
origin-centerremoves the redundancy and ensures consistent centered scaling behavior for the hero image.apps/docs/docs/integrations/forms/surveyjs/overview.md (1)
1-59: Well-structured overview with clear navigation and architecture explanation.The documentation effectively introduces the SurveyJS integration, provides clear navigation to related guides, and explains the modular structure. The installation command and environment variable documentation are concise and actionable.
apps/docs/docs/integrations/forms/surveyjs/usage.md (1)
1-222: Comprehensive and well-organized usage guide with clear patterns and examples.The document effectively covers three usage patterns (CMS block, direct component, and service injection), provides complete TypeScript examples, documents component props clearly, and includes a helpful sequence diagram showing the complete data flow. Best practices are practical and well-aligned with the architecture.
apps/docs/docs/integrations/forms/surveyjs/features.md (1)
1-154: Clear and comprehensive feature documentation with good balance of detail.The feature overview table provides quick reference, and each feature section contains helpful context about capabilities, implementations, and integrations. The descriptions align well with the usage patterns documented in usage.md.
apps/docs/docs/integrations/forms/surveyjs/_category_.json (1)
1-8: Correct category configuration linking to overview.The JSON structure is valid, positioning is consistent with overview.md (position 100), and the doc link correctly references the overview entry point.
apps/docs/docs/integrations/forms/surveyjs/how-to-setup.md (2)
1-124: Well-organized setup guide with clear, actionable steps.The documentation effectively guides users through installation, environment configuration, module registration, CMS setup, and verification. The troubleshooting section is practical. Cross-reference to the Strapi resources repository is helpful for CMS schema details.
103-103: Verify external documentation link validity.The reference to the Strapi resources repository (
https://github.com/o2sdev/openselfservice-resources) should be verified to ensure it remains current and accessible.apps/docs/docs/main-components/ui-library/theming/_category_.json (1)
1-8: Category configuration is well-formed.The JSON structure follows the expected pattern for documentation categories. Position 200 provides reasonable placement in the navigation hierarchy.
apps/docs/docs/main-components/ui-library/index.md (1)
10-12: Navigation structure and description update are appropriate.The link path correctly changes from the flat file (
./theming.md) to the new directory structure (./theming/), and the description accurately reflects the expanded scope with CMS configuration and custom theming guidance.apps/docs/docs/main-components/ui-library/theming/index.md (1)
1-35: Theming overview is well-structured and comprehensive.The index properly introduces the theming system, explains application levels clearly, and provides helpful cross-references and a quick-start workflow. The documentation hierarchy makes sense.
apps/docs/docs/main-components/ui-library/theming/css-themes.md (2)
228-250: Excellent practical guidance on theme definition.The theme definition section includes clear step-by-step instructions with code examples, and the tip linking to the shadcn/ui theme generator is helpful for developers new to theme creation.
40-40: No action needed – code reference syntax is supported.The syntax
1:59:packages/ui/src/theme.css(and similar on line 183) is a standard Docusaurus v3.9.2 feature. The @docusaurus/preset-classic preset natively supports code block line range references using the format ```start-end:filepath, which will correctly embed and display the specified lines from the referenced files in the published documentation. Both referenced files exist at their correct paths.apps/docs/docs/main-components/ui-library/theming/cms-configuration.md (1)
9-93: Clear and comprehensive CMS configuration documentation.The content is well-organized with explicit instructions for Strapi users, clear explanation of the theme data structure, and important notes on naming conventions and theme hierarchy that prevent common configuration mistakes.
apps/docs/docs/integrations/cms/strapi/content-model.md (1)
2-2: LGTM!Sidebar position adjustment aligns with the documentation restructuring, moving content-model down in the navigation hierarchy while features become the primary detailed reference.
apps/docs/docs/integrations/cms/strapi/how-to-setup.md (1)
136-136: Verify cross-reference to GraphQL documentation.Line 136 links to
./graphql.md. Ensure this file exists and is correctly positioned in the documentation structure (per the PR's new documentation organization).apps/docs/docs/integrations/cms/strapi/blocks.md (1)
1-84: LGTM!Comprehensive block reference with clear implementation status, helpful examples, and structured documentation of the block pattern (fragments, mappers, services). The FAQ example provides a concrete guide for implementing new blocks.
apps/docs/docs/integrations/cms/strapi/features.md (1)
1-178: LGTM!Comprehensive feature overview with clear status indicators, detailed descriptions, and appropriate documentation of unsupported features (Live Preview, Live Updates). Role mappings and cache integration are well-explained. Cross-references to GraphQL documentation are properly embedded.
apps/docs/docs/integrations/cms/strapi/graphql.md (1)
214-278: Excellent example usage lifecycle.The complete workflow from query definition through caching in CmsService is well-documented and provides clear guidance for implementing new operations. Type generation and SDK usage patterns are concrete and realistic.
apps/docs/docs/integrations/cms/strapi/overview.md (2)
9-15: LGTM!Excellent restructuring from a dense overview into a focused hub. The "In this section" navigation clearly guides users through the modular documentation. Cross-references to feature-specific guides (setup, features, blocks, content model, GraphQL) provide good organization.
39-40: External resource links are correct and accessible.The GitHub repository links referenced in lines 39-40 of overview.md are valid and accessible:
https://github.com/o2sdev/openselfservice-resources/tree/main/packages/cms/strapi/o2s(HTTP 200)https://github.com/o2sdev/openselfservice-resources/tree/main/packages/cms/strapi/dxp(HTTP 200)The repository structure and paths are confirmed to exist in the o2sdev/openselfservice-resources repository. No changes required.
apps/docs/docs/integrations/search/algolia/_category_.json (1)
1-8: Algolia docs category configuration looks correctLabel, position, and
link.idall align with the newintegrations/search/algolia/overviewentry, so this category should slot cleanly into the docs sidebar.README.md (1)
16-16: Blocks + integrations documentation updates are coherent and consistentThe new “Pre-built Blocks” feature, expanded project structure (apps/docs and packages/*), dedicated “Blocks” section, and refreshed integrations table (Contentful/Zendesk/Mocked/Algolia statuses) read clearly and match the rest of the integration docs added in this PR.
Also applies to: 57-71, 78-85, 92-99
apps/docs/docs/integrations/overview.md (1)
27-27: Algolia link correctly updated to new overview pathPointing the Algolia tile to
/docs/integrations/search/algolia/overviewmatches the new Algolia docs structure and avoids the removed old path.apps/docs/src/pages/product/integrations.tsx (1)
217-222: Product integrations page Algolia link is aligned with docsThe Algolia card now links to
/docs/integrations/search/algolia/overview, matching the new Algolia docs entry and category config.apps/docs/docs/integrations/search/algolia/overview.md (1)
5-49: Algolia overview page is clear and well-scopedThe overview gives a solid high-level description, links cleanly into setup/features/usage pages, and clearly states requirements and supported modules. This works well as the main entry point for the Algolia integration.
apps/docs/docs/integrations/search/algolia/usage.md (1)
5-356: Algolia usage documentation is comprehensive and consistentEndpoint description, payload/response structures, SDK and frontend examples, error cases, and pagination guidance all line up and give enough detail for consumers to integrate against
/searchconfidently.apps/docs/docs/integrations/tickets/zendesk/how-to-setup.md (5)
15-17: Good structure and clear installation instructions.The npm install command with workspace specification is correct and the explanation is clear. The command format matches the expected project structure for monorepo-based integrations.
27-53: Clear configuration section with helpful context.The before/after code examples and complete file output make it easy for users to understand exactly what changes are needed. The step-by-step approach with verification guidance is well-structured.
63-79: Comprehensive environment variable documentation with security guidance.The table format is clear, and the base64 encoding explanation with command-line examples is particularly helpful. The notes about token format and API URL structure provide essential context for users.
81-92: Well-organized credential retrieval steps with external links.The step-by-step instructions for obtaining Zendesk credentials are clear, and the base64 encoding guidance with tools/command-line examples is practical. The link to official Zendesk documentation is helpful.
128-138: Troubleshooting table is comprehensive and covers key scenarios.The table covers module not found, connection issues, authentication, environment variables, and the specific Users module dependency. The solutions are actionable and specific to the Zendesk integration.
apps/docs/docs/integrations/tickets/zendesk/overview.md (3)
9-13: Well-designed navigation structure for modular documentation.The "In this section" links provide clear guidance to users about available resources. The descriptions (step-by-step guide, overview of features, examples and API reference) help users understand which page to visit for their specific needs.
33-40: Quick start section is concise and appropriately links to detailed setup.The numbered steps are action-oriented and the reference to the detailed setup guide avoids over-complicating the overview page.
42-48: Requirements section is clear and specific.The list of requirements (Zendesk account, API token, Node.js environment, Users module) provides essential context. The note about TypeScript types from Zendesk OpenAPI specification is a nice detail.
apps/docs/docs/integrations/search/algolia/how-to-setup.md (5)
15-19: Clear and correct installation instructions.The npm install command with workspace specification is correct and well-explained.
70-74: Excellent security guidance on API key permissions.The emphasis on using a search-only API key and avoiding admin keys is critical security practice. The formatting and multiple reminders (line 72, 93) ensure users understand this important requirement.
105-118: Helpful explanation of index setup with sorting behavior.The detailed explanation of sorting index naming convention (
articles_publishedAt_desc) and the note that separate indexes are needed for each sort configuration is specific and practical. Users understand upfront that this affects their Algolia dashboard setup.
135-145: Troubleshooting table covers integration-specific issues.The troubleshooting covers package installation, connection issues, index configuration, API key permissions, and the integration import path. The solutions are actionable and specific.
146-153: Good next steps section with links to related documentation.The section appropriately links to features and usage documentation and suggests practical next actions (configure indexes, implement search).
apps/docs/docs/integrations/search/algolia/features.md (6)
9-37: Excellent documentation of generic search method with clear use cases.The method signature, explanation of what it does (including error handling for 404), and use cases make it clear when to use this method. The progression from signature → behavior → use cases is pedagogically sound.
60-156: Comprehensive query features documentation with examples and conversion details.Each query type is well-explained with examples. The pagination section's conversion formula (
page = Math.floor(offset / limit)) and default limit documentation are particularly helpful. The sorting section clearly explains the index name modification (articles_publishedAt_desc), which is a critical implementation detail.
158-177: Clear documentation of automatic features and error handling.The explicit list of error scenarios (missing env vars, missing index name, 404 handling, other API errors) with their outcomes helps users understand the integration's behavior. Logging behavior documentation at debug level is appropriately detailed.
179-225: Detailed article data model mapping with clear notes on behavior.The TypeScript type definition and the mapping table are well-organized. The note explaining that
updatedAtis used for bothcreatedAtandupdatedAtfields, and thatpermissions,tags, andsectionsare initialized as empty arrays, prevents user confusion about data consistency.
227-235: Explicit documentation of limitations prevents user confusion.Clearly stating which
SearchPayloadfields are not implemented (exists,notExists,filter) is important because it prevents users from assuming features are supported when they attempt to use them. This is good defensive documentation.
237-249: Response structure documentation with TypeScript example is clear.The TypeScript type with inline comments explaining each field is helpful. The note about optional fields (
page,nbPages,processingTimeMS) clarifies when these fields are present.apps/docs/src/pages/product/starters.tsx (1)
50-60: Digital starter links refactor aligns with new API
mainLink,secondaryLink, andotherLinksare wired correctly to the newStarterInfoSectionPropsshape, URLs match their labels (demo, Storybook, Docs, GitHub), and this should render clean, ordered CTAs.apps/docs/src/components/StarterInfoSection/index.tsx (1)
21-45: NewStarterInfoSectionPropsAPI matches starters usageThe split into
mainLink, optionalsecondaryLink, andotherLinksis clear and matches howcustomerPortalStarteranddigitalPortalStarterare now defined. Destructuring in the component is in sync with the interface, so this should be a straightforward internal API upgrade.
| ``` | ||
| component-{id}-{locale} | ||
| page-{id}-{locale} | ||
| app-config-{locale} | ||
| ``` |
There was a problem hiding this comment.
Add language specifier to cache key pattern code block.
The cache key pattern examples block is missing a language identifier. These appear to be plain text patterns rather than executable code, so mark as plain text or text.
Apply this diff to fix the code fence:
- ```
+ ```text
component-{id}-{locale}
page-{id}-{locale}
app-config-{locale}
- ```🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
46-46: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In apps/docs/docs/integrations/cache/redis/features.md around lines 46 to 50,
the fenced block of cache key pattern examples lacks a language specifier;
update the opening fence to ```text and keep the three pattern lines unchanged,
ensuring the closing fence remains ``` so the block is explicitly marked as
plain text.
|
|
||
| Start the API Harmonization server. Successful connection logs: | ||
|
|
||
| ``` | ||
| [REDIS] Successfully connected to redis | ||
| ``` |
There was a problem hiding this comment.
Add language specifier to code block showing expected output.
The code block displaying the expected log output is missing a language identifier. Add a language tag (e.g., plain, text, or log) or mark it as a code block without a language if representing plain shell output.
Apply this diff to fix the code fence:
- ```
+ ```log
[REDIS] Successfully connected to redis
- ```Alternatively, remove the code fence and present as plain text if this is just expected output documentation.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
106-106: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In apps/docs/docs/integrations/cache/redis/how-to-setup.md around lines 103 to
108, the fenced code block showing the expected log output lacks a language
specifier; update the closing and opening fences so the block is marked with a
language tag (e.g., ```log or ```text) or replace the fenced block with plain
text if you prefer no code fence, ensuring the displayed line reads: [REDIS]
Successfully connected to redis.
|
|
||
| Before you can start using the integration, you need to import the content model structure into your Contentful space. The content model defines the structure of your content types, including Pages, Templates, and Blocks that will be used in your application. | ||
|
|
||
| The content model includes predefined content types that are compatible with the Open Self Service framework, such as: |
There was a problem hiding this comment.
Fix: Use hyphen in "Open Self-Service" product name.
Per the static analysis hint, the product name should use a hyphen for consistency.
Apply this fix:
- Page content types for managing routes
+ Page content types for managing routes (Open Self-Service framework)Or if referring to the framework elsewhere:
- compatible with the Open Self Service framework
+ compatible with the Open Self-Service framework🧰 Tools
🪛 LanguageTool
[grammar] ~101-~101: Use a hyphen to join words.
Context: ...s that are compatible with the Open Self Service framework, such as: - Page conte...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In apps/docs/docs/integrations/cms/contentful/how-to-setup.md around line 101,
the product name "Open Self Service" should use a hyphen; update the text to
"Open Self-Service" to match the style guide and ensure consistency across the
docs, and scan nearby occurrences in this file to replace any other instances of
the unhyphenated form.
| ``` | ||
| ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ | ||
| │ O2S Frontend │────▶│ API Harmonizer │────▶│ Medusa Server │ | ||
| └─────────────────┘ └──────────────────┘ └─────────────────┘ | ||
| │ │ | ||
| │ Medusa.js SDK │ Admin API | ||
| │ HTTP Client │ Store API | ||
| ▼ ▼ | ||
| ┌──────────────────┐ ┌─────────────────┐ | ||
| │ Orders/Products │ │ Assets/Services │ | ||
| │ (native) │ │ (plugin) │ | ||
| └──────────────────┘ └─────────────────┘ | ||
| ``` |
There was a problem hiding this comment.
Specify language for ASCII diagram code block.
The fenced code block containing the ASCII architecture diagram is missing a language identifier. Add a language specifier (e.g., text or plain) to comply with markdown linting standards and improve syntax highlighting.
Apply this fix:
-```
+```text
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ O2S Frontend │────▶│ API Harmonizer │────▶│ Medusa Server │
└─────────────────┘ └──────────────────┘ └─────────────────┘🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
121-121: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
apps/docs/docs/integrations/commerce/medusa-js/overview.md lines 121-133: the
fenced code block containing the ASCII diagram lacks a language identifier; add
a language specifier such as "text" (e.g., change ``` to ```text) on the opening
fence so the block becomes ```text and leave the closing fence unchanged to
satisfy markdown linting and enable proper plaintext rendering.
| ## CMS configuration | ||
|
|
||
| The SurveyJS module integrates with your CMS (e.g., Strapi) to retrieve survey metadata. Before you can use surveys, you need to: | ||
|
|
||
| 1. **Configure your CMS integration**: Ensure your CMS integration (Strapi, Contentful, etc.) is properly configured in `AppConfig` | ||
| 2. **Create survey entries in CMS**: Create survey entries in your CMS with the following required fields: | ||
|
|
||
| | Field | Type | Required | Description | | ||
| |-------|------|----------|-------------| | ||
| | `code` | string | Yes | Unique identifier for the survey (e.g., `"contact-form"`) | | ||
| | `surveyId` | string | Yes | The SurveyJS survey ID from your SurveyJS service | | ||
| | `postId` | string | Yes | The SurveyJS post ID for form submissions | | ||
| | `surveyType` | string | Yes | Type of survey (typically `"survey"`) | | ||
| | `submitDestination` | string[] | Yes | Array of submission destinations (e.g., `["surveyjs"]`) | | ||
| | `requiredRoles` | string[] | Yes* | Array of roles required to submit the survey. Can be empty array `[]` for public surveys | | ||
|
|
||
| \* `requiredRoles` is required but can be an empty array for public surveys that don't require authentication. | ||
|
|
||
| **Example CMS entry:** | ||
| ```json | ||
| { | ||
| "code": "contact-form", | ||
| "surveyId": "72c90a02-6bfe-4e83-ba48-01f11752c234", | ||
| "postId": "a91349b1-0c4c-4b7a-b712-91f04a1e6e99", | ||
| "surveyType": "survey", | ||
| "submitDestination": ["surveyjs"], | ||
| "requiredRoles": [] | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Fix grammar issue in CMS configuration table.
Line 87 is missing a subject. Update "Can be empty array [] for public surveys" to "It can be empty array [] for public surveys" or similar to form a complete sentence.
Apply this diff to fix the grammar:
-| `requiredRoles` | string[] | Yes* | Array of roles required to submit the survey. Can be empty array `[]` for public surveys |
+| `requiredRoles` | string[] | Yes* | Array of roles required to submit the survey. It can be an empty array `[]` for public surveys |🧰 Tools
🪛 LanguageTool
[style] ~87-~87: To form a complete sentence, be sure to include a subject or ‘there’.
Context: ...of roles required to submit the survey. Can be empty array [] for public surveys ...
(MISSING_IT_THERE)
🤖 Prompt for AI Agents
In apps/docs/docs/integrations/forms/surveyjs/how-to-setup.md around lines 73 to
101, the CMS configuration table row for `requiredRoles` has a fragment "Can be
empty array `[]` for public surveys"; replace that fragment with a complete
sentence such as "It can be an empty array `[]` for public surveys" (note the
added subject "It" and the article "an") so the table description is
grammatically correct.
| {otherLinks.map((linkItem) => ( | ||
| <a | ||
| key={linkItem.label} | ||
| href={linkItem.link} | ||
| className="text-white! underline! hover:no-underline! text-sm font-medium" | ||
| target={linkItem.target} | ||
| > | ||
| {linkItem.label} | ||
| </a> | ||
| ))} |
There was a problem hiding this comment.
Add rel to target="_blank" other links for security best practices
For otherLinks, anchors can be opened in a new tab via target={linkItem.target}, but there’s no rel attribute. To avoid window.opener issues for external links, it’s safer to add rel="noopener noreferrer" when target="_blank":
- {otherLinks.map((linkItem) => (
- <a
- key={linkItem.label}
- href={linkItem.link}
- className="text-white! underline! hover:no-underline! text-sm font-medium"
- target={linkItem.target}
- >
+ {otherLinks.map((linkItem) => (
+ <a
+ key={linkItem.label}
+ href={linkItem.link}
+ className="text-white! underline! hover:no-underline! text-sm font-medium"
+ target={linkItem.target}
+ rel={linkItem.target === '_blank' ? 'noopener noreferrer' : undefined}
+ >📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| {otherLinks.map((linkItem) => ( | |
| <a | |
| key={linkItem.label} | |
| href={linkItem.link} | |
| className="text-white! underline! hover:no-underline! text-sm font-medium" | |
| target={linkItem.target} | |
| > | |
| {linkItem.label} | |
| </a> | |
| ))} | |
| {otherLinks.map((linkItem) => ( | |
| <a | |
| key={linkItem.label} | |
| href={linkItem.link} | |
| className="text-white! underline! hover:no-underline! text-sm font-medium" | |
| target={linkItem.target} | |
| rel={linkItem.target === '_blank' ? 'noopener noreferrer' : undefined} | |
| > | |
| {linkItem.label} | |
| </a> | |
| ))} |
🤖 Prompt for AI Agents
In apps/docs/src/components/StarterInfoSection/index.tsx around lines 81 to 90,
the anchor elements created from otherLinks set target from linkItem.target but
do not set rel; when target is "_blank" add rel="noopener noreferrer" to the
anchor to prevent window.opener security issues. Update the JSX to conditionally
include rel="noopener noreferrer" whenever linkItem.target === "_blank" (or
always include it) so external links opened in a new tab are safe.
tomaszpacior
changed the title
marcinkrasowski
left a comment
marcinkrasowski
left a comment
There was a problem hiding this comment.
@tomaszpacior please run format/linter and fix issues so that the pipeline succeeds, there are several broken links in docusaurus currently, and some prettier warnings https://github.com/o2sdev/openselfservice/actions/runs/19967951483/job/57264755450?pr=473
What does this PR do?
Summary by CodeRabbit
Release Notes
New Features
Documentation
Updates
✏️ Tip: You can customize this high-level summary in your review settings.