How to create a KIT website?

Project Structure

Following our project structure, the collection of our KITs documentation is developed in the ./docs-kits/kits folder, where each KIT is a subfolder called by its name for organisation purposes. The Data Chain KIT, for example, is defined here: ./docs-kits/kits/Data Chain Kit.

Each folder/KIT's content is structured in at least four pages/subfolders:

• Adoption View -> page_adoption-view.md
• Software Operation View -> page_software-operation-view.md
• Documentation -> page_documentation.md
• Software Development View/
  • Specification -> page_software-development-view.md
  • OpenAPI definition/
  • Another OpenAPI definition/
  • ...

Steps to add a NewKit documentation

1. Create a folder under the ./docs-kits/kits with the name of the KIT you are developing the documentation of

root
|--docs-kits
   |--kits
      |--NewKIT

2. Inside the NewKIT folder, add a page_adoption-view.md file with the content that suits your use case

root
|--docs-kits
   |--kits
      |--NewKIT
         |--page_adoption-view.md

3. Inside the NewKIT folder, add a page_software-operation-view.md file with the content that suits your use case

root
|--docs-kits
   |--kits
      |--NewKIT
         |--page_adoption-view.md
         |--page_software-operation-view.md

4. Inside the NewKIT folder, add a page_documentation.md file with the content that suits your use case

root
|--docs-kits
   |--kits
      |--NewKIT
         |--page_adoption-view.md
         |--page_software-operation-view.md
         |--page_documentation.md

5. Inside the NewKIT folder, add a Software Development View folder that contains a page_software-development-view.md file with the content that suits your use case

root
|--docs-kits
   |--kits
      |--NewKIT
         |--page_adoption-view.md
         |--page_software-operation-view.md
         |--page_documentation.md
         |--Software Development View
            |--page_software-development-view.md

6. To generate the OpenAPI based documentation of your KIT, please consult the Plugins section to configure your instance of the Docusaurus-OpenAPI-Docs in the docusaurus.config.js.

7. Add your newly created KIT documentation to the Kits sidebar page, by incorporating the following declaration in the sidebar object of the sidebarsDocsKits.js file:

const sidebars = {
    kits: [
        // copy from here...
        {
            type: 'category',
            label: 'New KIT name', //change here according your KIT
            link: {
                type: 'generated-index',
            },
            collapsed: true,
            items: [
                {
                    type: 'autogenerated',
                    dirName: 'kits/New KIT folder name given', //change here according your KIT
                },
            ],
        },
        // ...until here.
    ],
};

Note the sidebars may required bigger customisation based on your requirements, for that matters consult the official documentation

8. After the NewKIT documentation and the corresponding sidebar are created, you would want to make it accessible from the NavBar of the page. More specifically under the KITs dropdown menu:

This is easily handled by Docusaurus in the docusaurus.config.js file, where you'll need to add to the existing navbar object your newly created route and label (name of kit) to be added as a dropdown menu item. More specifically in:

themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      // ...
      navbar: {
        title: 'Eclipse Tractus-X',
        logo: {
          alt: 'Eclipse Tractus-X logo',
          src: 'img/logo_tractus-x.svg',
        },
        items: [
          // ...
          {
            type: 'dropdown',
            label: 'KITs',
            position: 'left',
            to: '/developer',
            items: [
              {
                to: '/docs-kits/kits/Business%20Partner%20Kit/Adoption%20View',
                label: 'Business Partner',
              },
              {
                to: '/docs-kits/kits/Data%20Chain%20Kit/Adoption%20View',
                label: 'Data Chain',
              },
              {
                to: '/docs-kits/kits/tractusx-edc/docs/kit/adoption-view/Adoption%20View',
                label: 'Connector',
              },
              {
                to: '/docs-kits/kits/Traceability%20Kit/Adoption%20View%20Traceability%20Kit',
                label: 'Traceability',
              },
              // ********* add here your object specifying "to" and "label" *********** 
            ],
          },
          // ...
        ]
      }
      // ...
    })

To know more about the NavBar options and how to implement this and other features in it please check the Docusaurus - NavBar Documentation

Important to know!

The results of your newly created KIT will be visible only (for now) in the Next version of the documentation. When a new version is due to be created, all of your additions plus the ones from other KITs will be taking part of said new released. To understand more about how Docusaurus handle the versioning and more specifically the versioning of multi-instance projects, please check the official documentation.

To access the Next and the rest of the versions, you'll notice a dropdown menu with all of them in the top-right corner of the NavBar that is only been displayed when the user is navigating any of the existing KITs.

Please check our Understanding our multi-instance and versioning behavoiur page, where we explain a little bit more in deep the structure of the project, the different instances of documentation, how to create versions and how the conditional rendering of the versions dropdown menu is been handled.