Repository structure
The documentation repository is structured for clarity and scalability. The main files and folders are:
When adding new content, always update the relevant map topic and make sure your files follow the established folder structure.
Content model
Our content model outlines the purpose of each content type we create and what to include when writing or updating an article. We use this model to ensure that our content consistently conveys the information people need to reach their goals with Cognite products. The content types ensure a consistent user experience, and any content type can be used with any product feature or audience. Consistency helps people develop mental models of the documentation and understand how to find information when they return to the site. It also makes maintaining and updating content more efficient.Content structure
Organizing content involves finding a balance between creating specific groups that help users locate what they need and limiting the number of hierarchy layers they must navigate. Too deep or wide hierarchies can make it hard for users to access the right information. We use these hierarchical levels:Content hierarchy levels
Collection
Collections are the top-level of the hierarchy and are organized around a workspace, role, or core workflow, such as “Industrial tools,” “Admin,” or “Data integration.” All collections appear on the site homepage and in the topbar. Collections can include a mix of categories, map topics, or articles.Category
A category is organized around a set of tasks or a feature, for example, “Field operations” or “Data modeling”. Within a category, include articles or map topics to subdivide content into more specific tasks. Category titles are task-based (begin with a gerund), and their intros describe the big-picture purpose or goal of using the feature.Map topic
Map topics group articles in a category by specific workflows or subtopics. We typically use Mintlify cards and columns to build map topics. Include at least two articles in each map topic. If a map topic has more than eight, consider splitting it into more specific map topics. Map topic titles are task-based (begin with a gerund).Article
Articles are the basic content units. Each article uses one of the content types described below. Each content type has a different purpose and structure, but they all share standard elements, like intros and callouts, to create a consistent experience.Content types
We use seven content types — concept, reference, procedure, quickstart, tutorial, troubleshooting, and map — each with a defined purpose, structure, and title pattern. Release and changelog content usesreference or concept, not a separate type. For the decision guide and per-type requirements, see Choosing your content type. Voice, Mintlify components, and accessibility standards: rules/cognite-styleguide.md in the repo (see Style and voice for a human summary).
Across the site, we often collectively refer to procedural content, tutorials, and quickstarts as “guides.”
Content order
We organize content consistently across categories, map topics, and articles. From broad to specific, use this order:- Conceptual content
- Reference content
- Procedural content
- Troubleshooting information
Content reuse
Use reusable snippets and variables to include the same content in multiple places. Avoid reusing large sections of articles unless there’s a specific reason. Store reusable texts in thesnippets folder. See Reusable snippets (external) for more information on how to create and use snippets.
Content components
We use Mintlify components to create a consistent user experience across all content. Components are reusable UI elements that provide structured ways to display information, organize content, and create interactive elements. Each component has specific properties and configuration options. The sections below describe when to use the most common components.Accordions
Accordions help create cleaner, more scannable documentation by allowing users to focus on what’s relevant to them while keeping additional information easily accessible. Example use cases include glossaries, troubleshooting information, or additional information that might interrupt flow. Learn more: Mintlify accordion component (external)Callouts
Callouts draw attention to important information and provide visual cues to readers about the type of content they contain. Readers often skip callouts. Prefer including critical information directly in the article text. If you use callouts, limit them to one or two per article and avoid placing multiple callouts next to each other. Callout types:- Info: Neutral contextual information or background details.
- Note: Supplementary information that supports the main content.
- Tip: Helpful suggestions, best practices, or pro tips.
- Check: Positive confirmations or success indicators.
- Warning: Important cautions or critical information about potential issues.
- Danger: Critical warnings about destructive actions or serious issues.
Cards and columns
We use cards and columns primarily to build landing pages and map topics to provide collection and category overviews. Learn more: Mintlify card component (external), Mintlify columns component (external)CodeGroup
CodeGroup allows you to use a tabbed interface to display code examples in different programming languages or for different tools. CodeGroups can only contain code blocks. Learn more: Mintlify code group component (external)Frames
Use frames to center illustrations and screenshots and add a caption to them. Don’t use frames for inline images, or if you want images to fill the full width without centering. While primarily used for images, frames can also wrap other components, for example Mermaid diagrams. Learn more: Mintlify frame component (external)Steps
Steps are a series of sequential actions that are part of a procedure, tutorial, or quickstart article.- Do
- Don't
- Use numbered steps for sequential tasks: When the order matters, use the Steps component to guide users through the process.
- Use the component for two or more steps: Use the Steps component when you have two or more sequential actions. If you have only one step, use a numbered list instead.
- Use clear, action-oriented titles: Begin step titles with verbs, for example, “Configure the API key,” “Install dependencies,” or “Test the connection.”
- Provide context: Always add explanations within steps, even if the title is self-explanatory.
- Define optional steps: Show when a step is optional, for example, “Optional. Configure authentication.”
Tabs
Organize related content in tabs that people can toggle between. Tabs can be useful for:- Organizing platform-specific instructions (macOS, Windows, Linux).
- Showing different approaches to the same task.
- Separating beginner vs. advanced content.
Further reading
- Choosing your content type — decision guide and per-type requirements
- Metadata reference — frontmatter fields and allowed values
- Mintlify navigation (external) — tabs, groups, and sidebar structure