note

This page mirrors the repository's root README.md. If you edit one, update the other.

Mambu documentation

This new Mambu documentation site is built with Docusaurus, a modern static website generator. It hosts the Mambu support documentation, as well as the following API references:

• Functions
• Streaming
• Payments
• V1

Installation

Install Yarn

Yarn is a package manager for Node.js and is required to run the script for generating the documentation.

npm install --global yarn

or when Yarn is already installed

yarn

Download fresh YAML/JSON files or adding new OpenAPI files to the collection

1. If you need to regenerate the OpenAPI files, you will need a valid private token from GitLab with the appropriate permissions for the APIs. You can store this in an .env file in the form PRIVATE_TOKEN="<TOKEN>". If you need one for testing, reach out to #ask-documentation.
2. Use the following command:

./scripts/retrieve-oas.sh

2. This retrieves all the OpenAPI files specified in the list, renames them, and puts them into the swagger_files directory.
3. You can also add a new OpenAPI file to this command by entering it in a new line, in the format <PATH_TO_RAW_OPENAPI_JSON_OR_YAML>|Renamed_file.json/yaml.
4. After this, run the ./rundocs.sh script again.

Convert YAML/JSON files

After installing Yarn, use the provided script to load the YAML/JSON files located in the "examples" folder and generate the documentation. After the completion of the script Mambu API Documentation will automatically start.

./rundocs.sh

Make sure to give execute permissions to the script using the chmod command:

chmod +x rundocs.sh

Run the development server

To load Mambu API Documentation in your local browser use:

yarn start

By default, this will load a local server at http://localhost:3000/.

AI Release Note Generation

To test the AI release notes generation script locally, you need AWS credentials for Bedrock.

1. Obtain temporary AWS credentials from the Mambu AWS account.
2. Use the provided setup script to update your .env file:

   bash scripts/setup-aws-creds.sh <ACCESS_KEY> <SECRET_KEY> <SESSION_TOKEN>

3. Run the test script:

   bash scripts/release-notes/test-ai-notes.sh v9.189.0

To run the deterministic release-note routing and version-format regression checks without Jira, Bedrock, or AWS credentials, use:

npm run test:release-notes

Non-CBE release notes, such as Notifications and Payments, should preserve the full release identifier in customer-facing titles, labels, and URLs. For example, notifications-v1.80.0 should render as v1.80.0 at /release-notes/notifications/v1-80-0/.

This browser preview is live, meaning that if you make and save changes, the browser will be refreshed in real-time with the changes.

Create a build

Create a build by using the following command:

yarn build

Run build locally

It's also possible to test the build locally by running the following command.

npm run serve

The site will be served locally at http://localhost:3000/ by default.

Fast builds for testing

Any changes made to the site configuration (as opposed to page content) will take a long time to build, because it needs to recompile the entire site. This can take upwards of half an hour, which makes testing code changes laborious. To bypass this problem and test code changes quickly, use the command IS_FAST_DEV=true npm run start. This will build a drastically cut-down version of the site, using the sidebars/sidebars.fastdev.js sidebar. You can add additional pages to this sidebar if you need to test it more deeply.

OpenAPI specifications

Make sure your files comply with the OpenAPI 2.0 or 3.+ specifications. It's possible to use Swagger Editor for this. We strongly recommend upgrading to 3.+ if you haven't done so yet.

How to contribute documentation

So, you've volunteered or been coerced into contributing to Mambu's documentation site.

The good news is, anybody is welcome to submit updates via the repository. The bad news is, you will need to use the repository to submit content changes directly, meaning that you will need some basic knowledge of git and Markdown.

To get started, refer to this readme. Feel free to reach out to the Documentation Team via Slack if you need any help.

Get started with Docusaurus

Please refer to the Docusaurus documentation to learn about its features: Docusaurus Guide. For example, if you wish to add a note block to your page, refer to the specification for admonitions. Because the content files of the support pages use .mdx (or .md) extensions, you can edit them in any text editor or IDE. MDX is an extension of Markdown, and is fully compatible with the entire Markdown specification, which can be found here: Markdown Guide. However, MDX can additionally make use of JSX components and plugins to display interactive elements inline with your documentation. For more information, refer to the guide here: MDX and React.

Due to the programmability offered by React, the creative possibilities really are endless. For example, you could embed a Mermaid UML diagram directly into your page using the Mermaid plugin. You can also render math equations using Katex.

Snippets

We use React components to embed reusable snippets for text that needs to appear in multiple places in the documentation. These can be found at src > components > snippets. If you wish to add a new one, pay close attention to the formatting requirements of the existing snippets, since they cannot render Markdown directly, and you will need to wrap the site's HTML along with any associated CSS.

Use Docusaurus in IntelliJ or another IDE

You can still use the IntelliJ Markdown Editor or Split Editor with MDX files. Just follow these steps:

1. Open your IntelliJ settings/preferences:
   • On macOS: IntelliJ IDEA > Settings
   • On Windows/Linux: File > Settings
2. Navigate to Editor > File Types.
3. In the list of Recognized File Types, find and select Markdown.
4. In the File name patterns section below, click the + (Add) button.
5. In the dialog that appears, type *.mdx and click OK.
   • Note that you may need to delete the existing standalone entry for .mdx first.
6. Click Apply and then OK to save your changes.

You can follow similar steps for a different IDE.

Add support pages to the navigation

Once you have added new support page(s) to your branch, they will also need to be added to the sidebar to become visible in the site.

1. Add new .mdx pages in the docs > docs directory.
   • Ensure that the pages have the correct front matter. Refer to other pages in the docs directory for examples.
2. Go to sidebars > primary-sidebars.js, search for the location where your new page(s) should reside, and add them using JSON notation.
3. The new pages should be immediately visible if you have used Yarn start, or you can rebuild them with Yarn build.

Add API or blog pages

API pages

While the API references are pulled in from various other repositories, the introduction pages can be added in this repository.

1. For API pages, navigate to docs > api > pages > API directory and make your changes accordingly.
2. To add them to the sidebar, navigate to sidebars > api-sidebars.js.

Blog pages

1. For blog pages, navigate to blog.
2. Refer to the documentation to ensure that the pages are correctly formatted regarding the naming convention and the use of metadata: blog.
3. If the pages have been added correctly, they will automatically appear in the Blog section of the site, in the chronological order defined in their filename.

Documentation Guidelines (Internal)

We maintain a set of internal guidelines for creating diagrams, styling, and best practices. These pages have their own sidebar and are not linked from the main site navigation.

To access them, ensure your local server is running (yarn start) and visit:

• Diagram Guidelines: Instructions for creating React-based SVG state diagrams, color palettes, and routing logic.
• Design System: How to work with the Mambu Design System for defining new styles.
• Merge Request Previews: How to use MR preview environments to share and review documentation changes before merging.