Skip to main content
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). 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? 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), and the 404-hugo-board.png/404-hugo-sad.png light/dark mascot pair shown on the custom 404 page (see Configuring Mintlify). 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 for how to use snippets.

​
Markdown file template

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