> ## Documentation Index
> Fetch the complete documentation index at: https://mage-staging.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://mintlify.com/docs/quickstart). This guide assumes you've configured your environment to [develop locally in Minflity](/contributing/documentation/overview#developing-locally-in-mintlify).

## Frontmatter

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

```md theme={null}
---
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](https://developers.google.com/style)
2. The [Apple Style Guide](https://support.apple.com/guide/applestyleguide/welcome/web)
3. The [Red Hat Guide](https://redhat-documentation.github.io/supplementary-style-guide/)
4. [Docs for Developers](https://docsfordevelopers.com/)

## 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:

```json theme={null}
{
    "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](https://www.w3schools.com/tags/att_img_alt.asp) and a `src`.

```html theme={null}
<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](https://github.com/mage-ai/assets/tree/main), or on GitHub through their [image upload service](https://stackoverflow.com/a/20959426).

## Code blocks

All code should be formatted using code blocks. Use Mintlify's [fenced code blocks](https://mintlify.com/docs/content/code) for simple examples. Multi-language blocks should use [Code Groups](https://mintlify.com/docs/content/components/code-group). Responses and requests, especially those living in our API docs, should use the Response Field and Request Field, respectively. Details can be found [here](https://mintlify.com/docs/api-playground/components/api/sticky-examples).

## Collapsable and numbered content

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

* [Accordions](https://mintlify.com/docs/content/components/accordion)
* [Accordion Groups](https://mintlify.com/docs/content/components/accordion-group)
* [Steps](https://mintlify.com/docs/content/components/steps)
* [Tabs](https://mintlify.com/docs/content/components/tabs)

Here are a few examples from our docs:

* [Run dbt](/guides/setup-dbt)
* [Quickstart](/getting-started/setup)