> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superoffice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Organization of repositories

> How SuperOfficeDocs repositories are organized into files and folders, including naming conventions and UID rules.

Git is an open-source version control system. The files are stored in repositories. GitHub is a web-based hosting service for Git repositories.

## File names and file extensions

* Use a descriptive name based on the top-level heading in the file.
* Use single hyphens as word separators. Don't use underscores or camel-case.
* Use lower-case letters, numbers, and dashes only.
* Omit articles and the word *and*.

**Naming conventions:**

* \<feature/context>-index.md (or index.mdx for landing pages)
* \<feature/context>-overview\.md (used when there is already an index file)
* \<feature/context>-getting-started.md
* \<feature/context>-\<crud>-\<item>.md
  * \<feature/context>-install.md
  * \<feature/context>-upgrade.md
  * \<feature/context>-config.md
  * \<feature/context>-debug.md
* \<feature/context>-faq.md
* \<feature/context>-options.md
* \<feature/context>-requirements.md
* \<feature/context>-scenarios.md
* \<feature/context>-security.md
* \<feature/context>-settings.md
* \<feature/context>-troubleshooting.md

If there are multiple features or contexts in a single folder, you need to specify that in the file names. Otherwise, the parent folder should make that clear.

### Example

A file named *create-company* has UID **crmscript-create-company** and is located in the *superoffice-docs/docs/company/howto/crmscript* folder.

Here, the filename follows the \<crud>-\<item>.md pattern and the parent folders *company/howto/crmscript* provide the context.

We need to add 'crmscript' to the UID to make it unique. However, there is no need to repeat the word 'company' and that it is a how-to is implied by the verb.

### Markdown (.md) vs MDX (.mdx)

Most content pages use the `.mdx` extension, since they use Mintlify's JSX components (`<Note>`, `<Tabs>`, and so on: see the [Markdown guide][1]). Plain `.md` is reserved for files with no JSX/component syntax at all: mainly snippets and a handful of pages that haven't needed a component yet.

If you add a component to a `.md` file, rename it to `.mdx` in the same change.

See [What is MDX?][3] for background on the underlying format.

## Folder organization

We use sub-folders to group similar content, images, and reusable snippets. The organization on GitHub only loosely resembles the structure on `docs.superoffice.com`.

At the root of the repo, there is a folder named *docs*. In it, you can find general pages that relate to the overall website and a set of sub-folders that match the features/APIs or common scenarios.

## Media folder

Media files aren't split per-folder. They live in one centralized location at the repository root, */media/loc/en/\<topic>/*, shared across all languages (there's no per-language split). Reference an image with a root-absolute path, for example `/media/loc/en/diary/open-diary.png`, regardless of which language folder the page itself lives in.

## Images folder

`/images/` holds site-wide branding/config assets referenced directly by `docs.json` — `og-background.png`, the social-preview thumbnail background (see [SEO and social previews][4]), and the `404-hugo-board.png`/`404-hugo-sad.png` light/dark mascot pair shown on the custom 404 page (see [Configuring Mintlify][5]). This is different from `/media/loc/en/<topic>/`, which holds per-topic content images, and from `/logo/`, which holds only the two required, fixed-filename logo files.

## Snippets subfolder

All major folders have a */snippets* subfolder for reusable content in that section. See [Markdown reference][1] for how to use snippets.

## Markdown file template

We use the [Blueprint extension][2] for Visual Studio Code. Available templates are located in the *blueprint-templates* folder at the root of the repo.

[1]: ./markdown-guide/index

[2]: ./markdown-guide/using-blueprint-templates

[3]: https://mdxjs.com/docs/what-is-mdx/

[4]: ./seo

[5]: ./configure-mintlify