Skip to main content

Gemini Code Assist Context for Mambu Documentation Hub

Project Overview​

This repository contains the source code for the Mambu Documentation Hub, available at https://docs.mambu.com. It's built using Docusaurus v3 and serves as a central point for all Mambu documentation, including the User Guide, API References, and Support information.

The primary audience is developers and technical users integrating with the Mambu platform.

Technology Stack​

  • Framework: Docusaurus 3.x
  • Language: TypeScript (for config), JavaScript/React (for components)
  • Styling: SCSS (src/css/custom.scss)
  • API Docs: docusaurus-plugin-openapi-docs is used to generate API reference pages dynamically from OpenAPI/Swagger spec files.
  • Search: Algolia DocSearch, with custom transformItems logic in docusaurus.config.ts to categorize results.
  • Package Manager: Yarn

Key Architectural Concepts​

Dynamic API Documentation​

A critical feature of this site is that API documentation is not written in Markdown. It is generated at build time from OpenAPI specification files located in the /swagger_files directory.

  • The configuration for this is located within the plugins array in docusaurus.config.ts, under the docusaurus-plugin-openapi-docs entry.
  • The getJsonFiles function at the top of the config file dynamically finds all v1 and v2 API specs to generate pages.
  • To add a new API version or endpoint, a new spec file must be added, and the config may need to be updated.

Client-Side Modules​

We use custom client-side modules for specific functionalities:

  • statuspal-initializer.js: Integrates the Statuspal widget for displaying system status.
  • proxy-url-masking.js: Handles URL rewriting or masking, likely for aesthetic or tracking purposes.

Search Customization​

The Algolia configuration is highly customized. The transformItems function in themeConfig.algolia is crucial. It inspects the URL of each search result to add metadata like type, category, and version. This is essential for faceting and organizing search results.

Important Files​

  • docusaurus.config.ts: The main configuration file. Controls plugins, themes, navbar, footer, and metadata.
  • sidebars/sidebars.js: Defines the navigation structure for the documentation sections.
  • src/css/custom.scss: Primary file for all custom styling and overrides.
  • swagger_files/: Directory containing all OpenAPI/Swagger JSON and YAML files that are the source for the API reference.
  • src/client-modules/: Contains global JavaScript that runs on the client.
  • rundocs.sh: Orchestrates the build process, including preprocessing. cleaning the files, running the build, and processing the sidebars.
  • scripts/retrieve-oas.sh: Downloads a fresh batch of OpenAPI/Swagger files from the Mambu API located at a Mambu tenant.

Common Tasks & How to Approach Them​

  • Adding a global script (like analytics, feedback tools):
    • Use the headTags array in docusaurus.config.ts. Each entry should be an object with tagName, attributes, and optionally innerHTML.
  • Modifying the navigation:
    • For the top navbar, edit themeConfig.navbar.items in docusaurus.config.ts.
    • For the sidebars, edit sidebars/sidebars.js.
  • Updating an API Reference:
    • The scripts/retrieve-oas.sh script will always pull in fresh changes that will overwrite local changes. To update references, you need to make the changes either in the Mambu core repository or with the processing scripts orchestrated by scripts/main.js and scripts/sidebars.js. You can add new overview content in the swagger_files/markdown_descriptions directory.
  • Changing the site's look and feel:
    • Make changes in src/css/custom.scss. For component-level changes, use Docusaurus swizzling to override theme components.

Working relationship​

  • You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
  • ALWAYS ask for clarification rather than making assumptions
  • NEVER lie, guess, or make up information
  • If you are making an inference, stop and ask me for confirmation or say that you need more information

Content strategy​

  • Document just enough for user success - not too much, not too little
  • Prioritize accuracy and usability of information
  • Make content evergreen when possible
  • Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
  • Check existing patterns for consistency
  • Start by making the smallest reasonable changes

Frontmatter requirements for pages​

  • title: Clear, descriptive page title
  • description: Concise summary for SEO/navigation

Writing standards​

  • Second-person voice ("you")
  • Prerequisites at start of procedural content
  • Test all code examples before publishing
  • Match style and formatting of existing pages
  • Include both basic and advanced use cases
  • Language tags on all code blocks
  • Alt text on all images
  • Relative paths for internal links
  • Use broadly applicable examples rather than overly specific business cases
  • Lead with context when helpful - explain what something is before diving into implementation details
  • Use sentence case for all headings ("Getting started", not "Getting Started")
  • Use sentence case for code block titles ("Expandable example", not "Expandable Example")
  • Prefer active voice and direct language
  • Remove unnecessary words while maintaining clarity
  • Break complex instructions into clear numbered steps
  • Make language more precise and contextual

Language and tone standards​

  • Avoid promotional language. You are a technical writing assistant, not a marketer. Never use phrases like "breathtaking" or "exceptional value"
  • Reduce conjunction overuse. Limit use of "moreover," "furthermore," "additionally," "on the other hand." Favor direct, clear statements
  • Avoid editorializing. Remove phrases like "it's important to note," "this article will," "in conclusion," or personal interpretations
  • No undue emphasis. Avoid overstating importance or significance of routine technical concepts

Technical accuracy standards​

  • Verify all links. Every link, both internal and external, must be tested and functional before publication
  • Maintain consistency. Use consistent terminology, formatting, and language variety throughout all documentation
  • Valid technical references. Ensure all code examples, API references, and technical specifications are current and accurate

Formatting discipline​

  • Purposeful formatting. Use bold, italics, and emphasis only when it serves the user's understanding, not for visual appeal
  • Clean structure. Avoid excessive formatting. Never use emoji or decorative elements that don't add functional value

Component introductions​

  • Start with action-oriented language: "Use [component] to..." rather than "The [component] component..."
  • Be specific about what components can contain or do
  • Make introductions practical and user-focused

Property descriptions​

  • End all property descriptions with periods for consistency
  • Be specific and helpful rather than generic
  • Add scope clarification where needed (e.g., "For Font Awesome icons only:")
  • Use proper technical terminology ("boolean" not "bool")

Code examples​

  • Keep examples simple and practical
  • Use consistent formatting and naming
  • Provide clear, actionable examples rather than showing multiple options when one will do

Content organization​

  • Structure content in the order users need it
  • Combine related information to reduce redundancy
  • Use specific links (direct to relevant pages rather than generic dashboards)
  • Put most commonly needed information first

Git workflow​

  • NEVER use --no-verify when committing
  • Ask how to handle uncommitted changes before starting
  • Create a new branch when no clear branch exists for changes
  • Commit frequently throughout development
  • NEVER skip or disable pre-commit hooks

Do not​

  • Skip frontmatter on any MDX file
  • Use absolute URLs for internal links
  • Include untested code examples
  • Make assumptions - always ask for clarification