Overview

Welcome to the Spectro Cloud documentation repository. To get started with contributions, please review the entire README.

For internal Spectro Cloud users, please review the contributions section of the Documentation & Education's teams home page.

There are two local development paths available; Docker based, and non-Docker based. To reduce complexities, we recommended the Docker based development approach.

Prerequisites

To contribute, we recommend having the following software installed locally on your workstation.

VScode or a text editor
Docker
git configured and access to github repository
Node.js v20 and npm.
Vale, version 3.6.0 or higher.

Local Development (Docker)

To get started with the Docker-based local development approach, ensure you are in the root context of this repository.

Initialize the repository by issuing the following command:

make init

Next, add your Palette API key to the .env file. Replace <your-palette-api-key> with your Palette API key.

PALETTE_API_KEY="<your-palette-api-key>"

[!IMPORTANT] You need a Palette API key to start the local development server. Refer to the Create API Key guide to learn how to create a Palette API key.

Issue the following command to build the Docker image and start the Dockererized local development server. The command may take several minutes to complete.

make docker-start

The local development server is ready when the following output is displayed in your terminal.

> spectro-cloud-docs@4.0.0 start
> docusaurus start --host 0.0.0.0 --port 9000

[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at: http://localhost:9000/

✔ Client
  Compiled successfully in 8.39s

client (webpack 5.88.2) compiled successfully

Open up a browser and navigate to http://localhost:9000 to view the documentation website.

To exit from the local development Docker container. Press Ctrl + Z.

Local Development Setup (Non-Docker)

Clone the repository and run the initialization script.

cd Work
git clone https://github.com/spectrocloud/librarium.git
cd librarium
make init

Next, add your Palette API key to the .env file. Replace <your-palette-api-key> with your Palette API key.

PALETTE_API_KEY="<your-palette-api-key>"

[!IMPORTANT] You need a Palette API key to start the local development server. Refer to the Create API Key guide to learn how to create a Palette API key.

Documentation Content

Create a branch to keep track of all your changes.

git checkout -b <branch_name>

Make changes to any markdown files in the docs/docs-content folder.

Start the local development server and preview your changes by navigating to the documentation page you modified. You can start the local development server by issuing the following command:

make start

When you are done with your changes, stage your changes and create a commit

git add -A && git commit -m "docs: your commit message here"

Creating Pages

The documentation website is structured in a sidebar with main pages and sub-pages. Main pages will contain an overview of the its sub pages.

Anatomy of a documentation page

The navigation sidebar will be something across all pages.

The header will have a search bar and some links to different other sections of the documentation (api)

The page content will be displayed under the header and next to the sidebar. On it's right there will be a table of contents menu that will extract all of the headers inside the content and display them in a list. This will follow the user as he scroll the page. On top of the table of contents there will be a github link to the content of the file. This can be used by users to submit changes to different sections of our documentation.

Main Pages

Create a page with the filename <url-using-dashes>.md in the docs-content folder of the content directory. For positioning the document in the sidebar, you can use sidebar_position: 1 in the front matter. To manage folders, create a _category_.json file with {position: 1} inside the desired directory.

Example of attributes

---
title: "Introduction"
sidebar_label: "Introduction"
description: "Palette API Introduction"
hide_table_of_contents: false
sidebar_custom_props:
  icon: "graph"
---

Front Matter Attributes

attribute	type	description
`sidebar_label`	string	used as the label for navigation
`title`	string	will appear on the browser window / tab as the title
`description`	string	the text to display when a page is shared in social media platforms
`sidebar_custom_props:` `icon: "graph"`	string	one of icons from https://fontawesome.com/icons?d=gallery
`hide_table_of_contents`	boolean	setting this to `false` will hide the page from the navigation
`sidebar_position`	number	the position of the page in the navigation sidebar. The pages are sorted ascending by this value
`toc_min_heading_level`	number	the minimum heading level to show in the table of contents. The default value for all documents is `2`.
`toc_max_heading_level`	number	the maximum heading level to show in the table of contents. The default value for all documents is `3`.
`tags`	array	A list of string that can be used for additonal categorization of content.
`keywords`	array	A list of strings that areused for SEO purposes.

Sub pages

Create a folder using the same name of the main page. Inside of it use the same name convention (<url-using-dashes>.md) to create subpages.

The index document for a folder follows the naming convention below. Here are some examples:

Named as index (case-insensitive): docs/Guides/index.md
Named as README (case-insensitive): docs/Guides/README.mdx
Same name as the parent folder: docs/Guides/Guides.md

Markdown Links and URLs

Markdown links use file path references to link to other documentation pages. The markdown link is composed of the file path to the page in context from the current file. All references to a another documentation page must end with the .md extension. Docusaurus will automatically remove the .md extension from the URL during the compile. The file path is needed for Docuasurus to generate the correct URL for the page when versioning is enabled.

The following example shows how to reference a page in various scenarios. Assume you have the following folder structure when reviewing the examples below:

.
└── docs
    └── docs-content
        ├── architecture
        │   ├── grpc.md
        │   └── ip-addresses.md
        ├── aws
        │   └── iam-permissions.md
        ├── clusters
        └── security.md

Same Folder

To link to a file in the same folder, you can use the following syntax:

![Insert a description here](name_of_file.md)

Because the file is in the same folder, you do not need to specify the path to the file. Docusaurus will automatically search the current folder for the file when compiling the markdown content.

So, if you are in the file grpc.md and want to reference the file ip-addresses.md, you would use the following syntax:

![A list of all Palette public IP addresses](ip-addresses.md)

Different Folder

If you want to link to a file in a different folder, you have to specify the path to the file from where the current markdown file is located.

If you are in the file security.md and want to reference the file iam-permissions.md, you have to use the following syntax:

![A list of all required IAM permissions for Palette](aws/iam-permissions.md)

If you are in the file grpc.md and want to reference the file iam-permissions.md, you have to use the following syntax:

![A list of all required IAM permissions for Palette](../aws/iam-permissions.md)

A Heading in the Same File

To link to a heading in the same file, you can use the following syntax:

[Link to a heading in the same file](#heading-name)

The # symbol is used to reference a heading in the same file. The heading name must be in lowercase and spaces must be replaced with a - symbol. Docusaurs by default uses dashes to separate words in the URL.

A Heading in a Different File

To link to a heading in a different file, you can use the following syntax:

[Link to a heading in a different file](name_of_file.md#heading-name)

For example, if you are in the file grpc.md and want to reference the heading Palette gRPC API in the file security.md, you would use the following syntax:

[Link to a heading in a different file](../security.md#palette-grpc-api)

The important thing to remember is that the # comes after the file name and before the heading name.

Exceptions

As of Docusarus 2.4.1, the ability to link to documentation pages that belong to another plugin is unavailable. To work around this limitation, reference a documentation page by the URL path versus the file path.

[Link to a page in another plugin](/api-content/authentication#api-key)

[!WARNING] Be aware that this approach will break versioning. The user experience will be impacted as the user will be redirected to the latest version of the page.

In future releases, Docusaurus will support linking pages from other Docusarus plugins. Once this feature is available, this documentation will be updated.

Redirects

To add a redirect to an existing documentation page you must add an entry to the redirects.js file. Below is an example of what a redirect entry should look like.

  {
    from: `/clusters/nested-clusters/`,
    to: `/clusters/sandbox-clusters`,
  },

Multi Object Selector

The Packs integration page and the Service Listings page use a component to display the various offerings. Packs intergations use the <Packs /> component, whereas the Service Tiers from App Mode use the <AppTiers /> component.

To add a Pack to the list complete the following actions:

Add a new markdown page for the Pack.
In the frontmatter set the type to the following value: type: "integration".
Populate the page with content.

To add a Service to the Service List complete the following actions:

Add a new markdown page for the App Mode Service.
In the frontmatter set the type to the following value: type: "appTier".
Populate the page with content.

Images or other assets

All images must reside in the static/assets/docs/images folder. All images must be in webp format. You can save png, jpg, or jpeg to the directory. The commit hook will convert the images to webp format. Or issue the command make format-images to convert the images to webp format.

![alt text](/clusterprofiles.png "cluster profiles example")

You can add a directory to to the images folder.

![alt text](/introduction/clusterprofiles.png "cluster profiles example")

Image Loading Image size loading can be customised. You can provide eager-load to images in the first fold of the image with high priority as LCP (Largest contentful Paint) for the page will not be affected

![alt text eager-load](/clusterprofiles.png)

Tabs component

To use the tabs component you have to import it from the shared folder

After that, you can use it like this

<Tabs queryString="platform">
  <TabItem label="AWS" value="aws">
    # AWS cluster Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  </TabItem>
  <TabItem label="VMware" value="vmware">
    # VMware cluster Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  </TabItem>
</Tabs>

Note: If you want to navigate from one page to another(which has tabs) and default tab to specific key then you must

provide an identifier to the Tabs component <Tabs queryString="clusterType">...</Tabs>
when creating the link to this page, include (in the query) the identifier provided and the value you want (eg: /clusters?clusterType=aws#section1)
the values can be one of the tab panel keys
additionally you may refer to different sections from the inner tab using the anchor points(using the #section-1)

YouTube Video

To use a Youtube video us the YouTube component.

In your markdown file, use the component and ensure you specify a URL.

<YouTube
  url="https://www.youtube.com/embed/wM3hcrHbAC0"
  title="Three Common Kubernetes Growing Pains  - and how to solve them"
/>

Points of Interest

<PointsOfInterest
  points={[
    {
      x: 20,
      y: 20,
      label: 1,
      description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      tooltipPlacement: "rightTop",
    },
    {
      x: 80,
      y: 100,
      label: 2,
      description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    },
    {
      x: 220,
      y: 230,
      description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      tooltipPlacement: "rightTop",
    },
  ]}
>
  *Markdown content*
</PointsOfInterest>

x and y properties refer to the coordinates of the point starting from the top-left corner of the markdown container.

Note

The x, y, and description properties are mandatory. The label and tooltipPlacement properties are optional.

If no label is specified, the default one is "+".

Possible placements are: topLeft, top, topRight, rightTop, right (default), rightBottom, bottomRight, bottom, bottomLeft, leftBottom, left, leftTop.

Tooltip

<Tooltip>tooltip content</Tooltip>

Notes

The tooltip icon can be customized by sending a font awesome icon

<Tooltip icon="atom">tooltip content</Tooltip>

If needed, the icon can be replace with text or other html tags using the trigger property:

<Tooltip trigger={<button>This is a button</button>}>
  <h1>This is a h1 inside the tooltip</h1>
</Tooltip>

If used inside a paragraph or other md elements the entire "block" needs to be on the same line

Hello <Tooltip trigger="world">tooltip content</Tooltip>! It's me Mario

Code Lines Highlighter

You can highlight specific lines in a block of code by adding coloredLines prop.

Example: ```js {2-4,5-7}. This will color the lines from 2 to 4 and from 5 to 7.

Components:

2-4 - lines interval to be colored
, - separator for different colored lines intervals

Example

https://docusaurus.io/docs/markdown-features/code-blocks#highlighting-with-comments

Hide ClipBoard Button

The copy button is shown by default in all code blocks. You can disable the copy button by passing in the parameter value hideClipboard in the markdown declaration of the code blocks.

Example

Result

Admonitions - Warning / Info / Tip / Danger / Tech Preview / Further Guidance

:::warning

Some **content** with _Markdown_ `syntax`.

:::

:::info

Some **content** with _Markdown_ `syntax`.

:::

:::tip

Some **content** with _Markdown_ `syntax`.

:::

:::danger

Some **content** with _Markdown_ `syntax`.

:::

:::preview

Some **content** with _Markdown_ `syntax`.

:::

:::further

Some **content** with _Markdown_ `syntax`.

:::

https://docusaurus.io/docs/markdown-features/admonitions

The content must have a new line at the beginning and at the end of the tag.

For guidance on using admonitions, refer to Spectro Cloud Internal Style Guide: Admonitions/Callouts.

Video

To add a video, use the following syntax. Ensure you capitalize the letter "V":

<Video src="/aws-full-profile.mp4"></Video>

<Video title="vsphere-pcg-creation" src="/cluster-creation-videos/vmware.mp4"></Video>

Badges

The following badges are available for use:

Note

All badges are globally available. No need to import them.

Technical Preview Badge

Technical Preview Badge

The technical preview badge is used to indicate that a feature is in technical preview. The badge is intended for release notes in the context of a list. The following is an example of how to use the technical preview badge. The component will automatically display the badge in the correct color based on the light theme (dark/light).

- <TpBadge /> Cluster Profile variables, a new feature that allows you to define variables in a cluster profile. This
  feature is in Tech Preview and is available only for Edge clusters. Profile variables allow you to define variable
  types, apply validation, and more. Refer to the Cluster Profile Variables documentation to learn more about profile
  variables.

Simple Card Grid

This is a custom component that creates a grid of simple text cards with two columns, styled according to our color scheme. The rows of cards are dynamically created according to the list of specified cards.

<SimpleCardGrid
  cards={[
    {
      title: "Lorem Ipsum",
      description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      buttonText: "Learn more",
      relativeURL: "./link",
    },
    {
      title: "Lorem Ipsum",
      description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      buttonText: "Learn more",
      relativeURL: "./link",
    },
    {
      title: "Lorem Ipsum",
      description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      buttonText: "Learn more",
      relativeURL: "./link",
    },
  ]}
/>

Tutorials Sidebar

This section describes how to publish new tutorials and add new categories to the Tutorials sidebar.

Add a New Category

To add a new sidebar category to Tutorials, create a new directory under docs/docs-content/tutorials. For example, let's add a directory called new-tutorials.

Note

Each category directory must have at least one .md file to render in the sidebar. If you add an empty directory to sidebars.js, the build will break.

.
├── _category_.json
├── cluster-deployment
│   ├── _category_.json
│   ├── pcg
│   │   ├── _category_.json
│   └── └── deploy-app-pcg.md
└── new-tutorials
    ├── _category_.json
    └── new-tutorial

Then, add the following code to the tutorialSidebar array in the sidebars.js file.

tutorialSidebar: [
  {
    type: "category",
    label: string,
    className: "category",
    collapsed: false,
    collapsible: false,
    items: [{ type: "autogenerated", dirName: "tutorials/new-tutorials" }],
    customProps: {
      icon: string,
    },
  },
  ...
];

Consider the following example for reference.

tutorialSidebar: [
    {
      type: "category",
      label: "Edge",
      className: "category",
      collapsible: false,
      collapsed: false,
      items: [{ type: "autogenerated", dirName: "tutorials/edge" }],
      customProps: {
        icon: "microchip",
      },
    },
  ...
];

Publish New Tutorials

To add tutorials to an existing category, create a new .md file in the respective directory under docs-content/tutorials and follow the guidance outlined in Creating Pages.

Partials Component

This is a custom component that allows you to create and use Docusaurus' Import Markdown functionality.

Important

Docusaurus does not provide the ability to dynamically configure table of contents. See this issue for more information. This means that you should avoid adding headings to partials that you intend to use with the Partials Component.

If you require headings, then you should import your partials using the guidance on the Docusaurus Import Markdown page.

Partials must be created under the _partials folder. They must be named using an _ prefix and the *.mdx filetype. Partials may be organised in any further subfolders as required. For example, you could create _partials/public-cloud/_palette_setup.mdx.

In order to aid with organisation and categorization, partials must have a partial_category and partial_name defined in their frontmatter:

---
partial_category: public-cloud
partial_name: palette-setup
---

This is how you set up Palette in {props.cloud}.

Partials are customized using properties which can be read using the {props.field} syntax.

Once your partial has been created, run the make generate-partials command to make your partial available for use. This command will also be invoked during the make start and make build commands.

Finally, you can reference your partial in any *.md file by using the PartialsComponent, together with the specified category and name of the partial:

<PartialsComponent
  category="example-cat"
  name="example-name"
  message="Hello!"
/>

The snippet above will work with the example partial we have in our repository, so you can use it for testing.

Note that the message field corresponds to the {props.message} reference in the _partials/_partial_example.mdx file.

Internal Links

Due to the complexities of Docusaurus plugin rendering, links do not support versioning in *.mdx files. If you want to add an internal link you will have to use the VersionedLink component inside the *.mdx file.

---
partial_category: public-cloud
partial_name: palette-setup
---

This is how you set up Palette in {props.cloud}.

This is an <VersionedLink text="Internal Link" url="/getting-started/additional-capabilities"/>.

The path of the link should be the path of the destination file from the root directory, without any back operators ... External links can be referenced as usual.

Palette/VerteX URLs

A special component has been created to handle the generation of URLs for Palette and VerteX. The component is called PaletteVertexUrlMapper. This component is intended for usage withing partials. You can use the component to change the base path of the URL to either Palette or VerteX. The component will automatically prefix the path to the URL. The component has the following props:

edition - The edition of the URL. This can be either Palette or Vertex. Internally, the component will use this value to determine the base URL.
text - The text to display for the link.
url - The path to append to the base URL.

Below is an example of how to use the component:

- System administrator permissions, either a Root Administrator or Operations Administrator. Refer to the
  <PaletteVertexUrlMapper
    edition={props.edition}
    text="System Administrators"
    url="/system-management/account-management"
  /> page to learn more about system administrator roles.

In cases where Palette and Vertex pages have different URLs beyond the base path, the component will accept the following props:

edition - The edition of the URL. This can be either Palette or Vertex. Internally, the component will use this value to determine the base URL.
text - The text to display for the link.
palettePath - The Palette path to append to the base URL.
vertexPath - The VerteX path to append to the base URL.

Below is an example of how to use the component when the URLs are different:

- System administrator permissions, either a Root Administrator or Operations Administrator. Refer to the
  <PaletteVertexUrlMapper
    edition={props.edition}
    text="System Administrators"
    palettePath="/system-management/account-management"
    vertexPath="/system-management-vertex/account-management"
  /> page to learn more about system administrator roles.

Packs Component

The packs component is a custom component that displays all packs available in Palette SaaS by querying the Palette API at api.spectrocloud.com. The component is powered by a custom plugin that fetches the data before a build or a local development server start.

Note

The data is stored in the file .docusarus/packs-integration/api_pack_response.json once all the packs are fetched. The logos are stored in static/img/packs/. If you remove the .docusarus folder, the plugin will fetch the packs again. If the pack's data is present, the plugin will skip re-downloading the data. If you want to remove the packs data and trigger a new fetch, you can issue the following command make clean-packs.

Pack descriptions are stored in a JSON file maintained by the documentation team. The JSON file is located at /static/packs-data/packs_information.json. To add an entry for a new pack, add the following JSON object to the file.

{
  "name": "insert the name of the pack. DO NOT USE THE DISPLAY NAME",
  "description": "insert description here"
}

Some things to keep in mind related to descriptions. If the local development server is active and you make changes to the /static/packs-data/packs_information.jsonfile, the changes will not be reflected in the pack component. You must stop and restart the local development server to observe the changes. The same applies to the build process. Another thing to remember is to reference a pack by the name used in the Palette API, not the display name. You can find the pack's name in the description component or by looking at the URL of the pack's page.

Exluding Packs

You can specify a list of packs to exclude from the packs component. To exclude a pack, add the pack name to the exclude_packs.json file.

[
  "palette-upgrader", 
  "csi-aws-new", 
  "inser-pack-name-here"
]

Excluded packs are not displayed in the packs component.

Disable Plugin

To disable the packs plugin, you can set the DISABLE_PACKS_PLUGIN environment variable to true. This will prevent the plugin from running and fetching the packs data. The packs component will not display any data if the plugin is disabled.

export DISABLE_PACKS_PLUGIN=true

Settting the DISABLE_PACKS_PLUGIN environment variable to true will also have the following effects:

The PDE/App Mode Packs are still displayed.
All production pack pages are added to the redirects file. This is to prevent broken URLs.
Fallback logic is activated in the PacksReadme, PacksInformation, and Packs components. Redirect to the integrations/ page is the new behavior.
The Packs list page will display a warning message indicating that the packs data is not available.

README Content

The pack component will display a Pack's README file if it exists. The README content comes from the Palette API. Depending on the available content, the packs component will display the README content, the additional details content, or a message indicating that no content is available. Refer to the table below for the different scenarios.

README Available	Additional Details File Available	Content Displayed
✅	✅	Both README and Additional Details content is displayed.
✅	❌	Only the README content is displayed.
❌	✅	Only the Additional Details content is displayed.
❌	❌	A message indicating that no content is available.

Additional Details Content

To display the Additional Details content, create a markdown file with the same name as the pack in the the docs/docs-content/integrations/ content folder. For example, if the pack name is ubuntu-aws, you would create a markdown file called ubuntu-aws.md. The additional details content requires you to follow the Packs layout guide.

If you want to add content specific to a version, include the following heading and tabs component in the markdown file.

## Versions Supported

<Tabs queryString="parent"> -> Tabs for different versions
<TabItem label="1.1.x" value="1.1.2">
 Insert content here as needed. Create more `TabItem` components as needed.
</TabItem>
</Tabs>

Warning

Ensure theTabs component has the queryString prop set to parent. This is required for the component to work. The Tabs component must also have a ## Versions Supported heading. If you do not follow this format, the content will not be displayed correctly, and as a result, actual tabs will be displayed, and the pack will lose the ability to automatically display the content for the select version the user has specified in the version drop-down.

The packs component will always display the top-level tab content, so if you add content for a new version, ensure the new TabItem component is the first in the list. If a new pack version does not have a respective tag, the latest version content will be displayed automatically.

Links

When authoring additional details content, you must use the <VersionedLink /> component to link to other documentation pages. The component is required to ensure that the links are versioned correctly. Refer to the Internal Links section for more information.

If you want to link to a heading inside the pack component, you must also use the <VersionedLink /> and include the path to the component followed by the heading id. The following is an example of how to link to a heading inside the pack component. Take note of the # symbol followed by the heading id.

<VersionedLink
  text="Change Cluster DNS Service Domain"
  url="/integrations/packs/?pack=kubernetes-eks#change-cluster-dns-service-domain"
/>

Omit the version=xxxx&parent=xxxx value that is part of the query string. If you include the version and parent values, the link will not work as expected.

Link to a Pack

You must use the <VersionedLink /> component to link to a pack. The following is an example of how to link to a pack. For more information, refer to the Internal Links section.

<VersionedLink text="Change Cluster DNS Service Domain" url="/integrations/packs/?pack=kubernetes-eks" />

If you do not use the <VersionedLink /> component, the link will not be versioned correctly, and the build will fail.

Netlify Previews

By default Netlify previews are enabled for pull requests. However, some branches do not require Netlify previews. In the netlify.toml file, a custom script is used to determine if a Netlify preview should be created. The script is located in the scripts/netlify.sh file. If you need to disable Netlify previews for a branch, add the branch name to the allowed_branches variable in the scripts/netlify.sh file.

Approvers/Reviewers

The content in this repository requires approval from the documentation team. The approval rules can be found in the CODEOWNERS file. Only members of the documentation team may modify this file.

Check Writing

We leverage Vale to help us enforce our writing style programmatically and to avoid common writing mistakes. The writing checks are executed upon a pull request. You may also conduct a writing check locally by using the Vale CLI. Follow the steps below to install the Vale CLI and execute the writing checks.

Start by installing Vale by following the installation steps in the Vale documentation.

Next, download the required Vale plugins.

make sync-vale

To execute the writing check, issue the command below. The command below will identify files that are modified by comparing the current git branch against the master branch. Ensure your local master branch is up to date for accurate results.

make check-writing

You may also use the Vale CLI to directly scan a file and receive feedback.

Example:

vale content/docs/08-user-management.md

Vale

The vale.ini file contains the configuration for Vale. We use the Spectro Cloud Vale package to enforce our writing style.

Check Formatting

We use Prettier to maintain uniform and consistent formatting across the docbase. When you commit changes, Prettier formats the staged files automatically. Then, once you create a pull request, it verifies that the formatting in all files complies with our Prettier configuration.

Note

The CI will automatically format the files and commit the changes, if necessary.

To manually check the formatting before pushing your work upstream, execute the following command in your terminal:

make format-check

Console output if all files are formatted:

Checking formatting...
All matched files use Prettier code style!

Console output if some of the files require re-formatting:

Checking formatting...
[warn] README.md
[warn] Code style issues found in the above file. Run Prettier to fix.

To manually format all files, issue the following command:

make format

Known Caveats

When using callouts/admonitions, pay attention to their syntax.

<!-- Prettier doesn't change this -->
:::note

Hello world

:::

<!-- Prettier changes this -->

:::note
Hello world
:::

<!-- to this, interfering with the admonition rendering and breaking JSX components -->

::: note Hello world:::

When you add JSX or HTML syntax, Prettier can introduce empty artifacts around them {" "} to ensure that whitespace is preserved in the rendered output – a helpful feature in React development. However, Docusaurus can sometimes parse them as valid HTML, making these artifacts visible to readers. For this reason, check your docs before pushing changes upstream and remove any {" "} you find.

Release

To create a new release, use the following steps:

Create a release branch. Use the following naming pattern release-X-X
Create a commit using the following commit message feat: updating documentation for release-X-X. Replace x-x with the upcoming release number.
Push up the commit and create a new pull request (PR).
Merge PRs related to the upcoming release into the release-X-X branch.
Merge the release branch.
Create a new branch from the master branch. Use the following naming pattern version-X-X. This brach is used for versioning the documentation.
Push the new version branch to the remote repository.
Trigger a new build so that the new version is published.

The semantic-release logic and the GitHub Actions in the release.yaml will ensure the new release tag is created.

Warning

Do not use feat,perf, fix, or other semantic-release key words that trigger a version change. Use the commit message prefix docs: yourMessageHere for regular documentation commits.

Versioning

Note

Detailed documentation for versioning can be found in the internal Versioning guide.

All versioned content belongs to a specific version branch. The version branch name follows the naming convention version-X-X. The version branch is used to generate versioned content.

There are three files that are used for generating versioned content:

versions.sh - A bash script that loops through all the version branches and generates the versionioned content.
update_docusaurs_config.js - A node script that updates the docusaurus.config.js file with all the required vesioning parameters.
versionsOverride.json - A JSON file that contains the versioning overrides. These values are used to update the docusaurus.config.js file with non-default values.

Build Versioned Content Locally

To build versioned content locally, use the following steps:

Issue the following command to generate the versioned content.

make versions

Start a local development server to view the versioned content.

make start

Compile the versioned content to ensure a successful build.

make build

Remove the versions.json file and discard the changes to the docusaurus.config.js file. Use the following command to remove all version artifacts.

make clean-versions

Warning

The docusaurus.config.js file is updated by the update_docusaurus_config.js script. DO NOT commit this file with the updated changes.

Files

README.md

Latest commit

History

README.md

File metadata and controls

Overview

Prerequisites

Local Development (Docker)

Local Development Setup (Non-Docker)

Documentation Content

Creating Pages

Anatomy of a documentation page

Main Pages

Front Matter Attributes

Sub pages

Markdown Links and URLs

Same Folder

Different Folder

A Heading in the Same File

A Heading in a Different File

Exceptions

Redirects

Multi Object Selector

Images or other assets

Tabs component

YouTube Video

Points of Interest

Tooltip

Code Lines Highlighter

Hide ClipBoard Button

Admonitions - Warning / Info / Tip / Danger / Tech Preview / Further Guidance

Video

Badges

Technical Preview Badge

Simple Card Grid

Tutorials Sidebar

Add a New Category

Publish New Tutorials

Partials Component

Internal Links

Palette/VerteX URLs

Packs Component

Exluding Packs

Disable Plugin

README Content

Additional Details Content

Links

Link to a Pack

Netlify Previews

Approvers/Reviewers

Check Writing

Vale

Check Formatting

Known Caveats

Release

Versioning

Build Versioned Content Locally