Documentation

Pages

You can find the respective files of all content pages in src/content. All new pages must be created as MDX files in this directory. MDX allows you to use JSX in your Markdown content, in addition to standard Markdown syntax.

The page URL corresponds to the file system path by default. For example, an MDX file in src/content/getting-started/installation.mdx will render a page in docs.commercetools.com/getting-started/installation.

You can freely organize pages according to the website structure in src/data/navigation.yaml.

Markdown frontmatter

All content pages must contain some metadata enclosed within the --- lines in the frontmatter section. The frontmatter section is a leading section of a file that allows you to add key-value pairs that define the properties of a content page.

---
title: The title of this page
---


This is the actual page content.

We support the following key-value pairs in the frontmatter section:

  • title (string): use (mandatorily) to define the title of a page. It can have the same value as the title in src/data/navigation.yaml, or longer.

  • beta (boolean): use to indicate if BETA should be displayed for an entire page.

    You can use BETA in other places of a file apart from the frontmatter section. For more information, see Beta section.

  • excludeFromSearchIndex (boolean): use to exclude a page from being indexed by web crawlers. This option effectively sets the robots="noindex" meta attribute.

    This doesn't work with Algolia's Docsearch crawler currently.

  • navLevels (number): use to reduce the depth of right-hand index navigation for pages where it could get too long to fit all headings in the screen. In addition the Child section navigation helps you to keep the index navigation short.

  • wideLayout (boolean): use to make a page responsive and compatible for large viewport sizes. When used, the page can go into a two-column content space. For more information, see <SideBySide> component.

  • showTimeToRead (boolean): use to show the reading time of a page. If the timeToRead frontmatter is not defined, gatsby will analyse the page and determine the reading time.

  • timeToRead (number): use to set the reading time of a page. If defined, it replaces the automatically generated value from gatsby.

    This only works if the showTimeToRead frontmatter is defined and true.

  • planTags (array of string): use to indicate what plans are associated to the page.

  • products (array of string): if defined in a page, it overrides the site wide products setting which affects the algolia search indexer. This setting is useful for helping indexing correctly specific pages that are part of a site but their focus is on different products.

  • overrides (an object) with the following properties:

    • siteTitle (string): use to override the site title for a specific page. (for example in Glossary page)

    • siteBreadcrumbs (string): use to override the site root breadcrumb shown in the header for a specific page.

    Example:

---
title: The title of this page
planTags: [plan1, plan2]
products: [aiAssistant, additionalProduct]
---


This is the actual page content.

You can use <PlanTag /> in other places of a file apart from the frontmatter section. For more information, see Plan section.

JSX components

As mentioned earlier, it is possible to render JSX components within MDX files. The components must be added as XML tags, like HTML elements. For example:

<Subtitle>
Content inside the component.
</Subtitle>

You can use the following JSX components:

  • <Subtitle>: use to provide a brief information about the page besides the title. For more information, see Titles and headings.

  • <Info>: use to add any additional information.

  • <Warning>: use to add a warning message.

  • <Error>: use to add an error message.

  • <Anchor>: use to insert a custom anchor on any part of the document such as lists, paragraphs, etc. You can navigate to specific parts of the document (that are not headings) using anchor links. It is also useful when a document has multiple headings with the same text, or when heading names change and old third-party links continue to work. For more information, see Custom anchors.

    You cannot override ID generation of the site generator. It adds additional named anchors and IDs have precedence.

  • <ChildSectionsNav parent="a-section-slug" />: use to add a table of contents containing links to all subsections of the given parent. For more information, see Child section navigation.

  • <SideBySide>: use to wrap two content blocks side by side on wide viewport sizes. This feature is enabled by setting the wideLayout frontmatter option.

  • <MultiCodeExample>: can be wrapped around multiple markdown code blocks to show them as one code block with a language selector. Read more...

  • <Glossary>: can be wrapped around a term in body text. The UI feature is not implemented yet, but the kit allows authors to already set the tags invisibly to later enable it.

  • <PageRedirection> : can be used to redirect the page to another page after a certain time. It accepts two props: to a string representing the path to redirect to and delay a number representing the milliseconds to wait until redirect