Mage uses Mintlify as our documentation framework. Mintlify provides hosting and deployment for our docs, which makes editing quite simple. In this guide, we’ll discuss different “levels” of contributing to our docs, starting from simplest to most advanced.
All of our docs are written in plain text as Markdown files. If you’re not familiar with Markdown, check out this guide to get started. You can take a look at the structure and contents of our docs by navigating this site and checking out the docs directory on GitHub.
Level 1: Suggesting Edits 🦸🏻♂️
The very simplest way to contribute to the Mage docs is directly in the browser, using GitHub’s file editing feature. This is a great way to suggest small edits to existing docs, but it’s not the best way to add entirely new docs or complex formatting, images, etc.
To make edits, simply click on the “Suggest Edit” button at the bottom of every page. This will open a new tab with the file you’re editing. Make your changes, then click “Commit changes.” This will open a new pull request with your changes. Be sure to add appropriate details to your pull request & tag
@mattppal. Once the pull request is merged, your changes will be live on the site!
Level 2: Add complex components 💪
To add images to the Mage docs, you’ll need to contact a team member or host the images in GitHub. Our assets currently live in a private repo to keep the docs repo lightweight.
Reach out in Slack if you’re editing documentation that requires additional assets and we’ll get them hosted for you.
When adding images, we use centered divs or the Mintlify frame component. You can see the code in this page for examples of both.
To learn more about Mintlify-specific elements, visit the Mintlify docs here. You can add things like accordion groups, interactive lists, html elements, and more. Anything you can do in Mintlify, you can do in our docs.
Level 3: Add entirely new docs 🪄
Adding a new page
Each page is an MDX file that should begin with the following metadata syntax with
--- at the start and end. Here are basics to get you started:
Once you add a new page in the appropriate folder in our
docs directory, you’ll need to add it to our site navigation. That is accomplished through the
mint.json file in the root of our
You’ll need to add a new entry to the
pages array in that file. The
path should be the relative path to your new page, and the
title should be the title of your page. Paths in
mint.json should not include file extensions.
Developing locally in Mintlify
If you really want to level up your docs contributions, you can create a local development environment. This will allow you to see changes live as you make them on your machine.
Follow the instructions from Mintlify here to get started. Once configured, you’ll be able to run a local server that will allow you to see your changes in real-time.
cd mage-ai/docs +
mintlify dev and you’ll be able to navigate to a live version at
Some elements in Mintlify have icons. Those are sourced from fontawesome. Any icon you find there can be added as an icon to the Mage docs, where appropriate. We only add icons to top-levl items in our sidebar.
Level 4: Adding entirely new sections 🧙🏻♂️
If you’d like to contribute a larger, more structured section of our documentation, please reach out to a member of our team via Slack. They’ll be able to guide you through the process of making sweeping changes.
Was this page helpful?