Style Guide

Mage Docs are written in Markdown and deployed via Mintlify. This page is a style guide for contributing new documentation.

To understand more about Minlify, including what’s supported and what’s not, check out the Minlify Quickstart. This guide assumes you’ve configured your environment to develop locally in Minflity.

Frontmatter

Each document should have a frontmatter section, denoted by the characters ---, for example:

---
title: "Style Guide"
sidebarTitle: "Style Guide"
description: "Mage Docs are written in Markdown and deployed via Mintlify. This page is a style guide for contributing new documentation."
---

Frontmatter must include title, sidebarTitle, and description

Content

Markdown content should use h2 headers (##) for top-level sections, h3 headers (###) for sub-sections, and h4 headers (####) for sub-sub-sections.

If you’re looking for resources on how to write better documentation, we recommend:

1. The Google Developer Documentation Style Guide
2. The Apple Style Guide
3. The Red Hat Guide
4. Docs for Developers

Sidebar

To add your new documentation to the sidenav, you’ll need to edit mint.json in docs/. The nested json serves to organize high-level pages. You’ll need to find the “Group” your page corresponds to, then add the page as a new item in that group’s pages array, as follows:

{
    "group": "Documentation",
    "icon": "book",
    "pages": [
    "contributing/documentation/overview",
    "contributing/documentation/style-guide",
    "YOUR_NEW_PAGE"
    ]
}

Note that pages should be paths relative to the docs/ directory and should not contain an extension.

Images

Images should be inserted using an <img> tag with a <Frame> component. This is Mintlify functionality that helps keep our images consistent & pretty. Each image should have an alt property and a src.

<Frame>
    <img alt="Something super interesting" src="https://github.com/mage-ai/mage-ai/assets/59450879/6e04feeb-684a-4594-ba93-54acda76a623">
</Frame>

Images should not link to external urls and should be hosted in our assets repo, or on GitHub through their image upload service.

Code blocks

All code should be formatted using code blocks. Use Mintlify’s fenced code blocks for simple examples. Multi-language blocks should use Code Groups. Responses and requests, especially those living in our API docs, should use the Response Field and Request Field, respectively. Details can be found here.

Collapsable and numbered content

To create beautiful, collapsable or numbered content, check out the following resources in Mintlify:

• Accordions
• Accordion Groups
• Steps
• Tabs

Here are a few examples from our docs:

• Run dbt
• Quickstart