README

Naming For documentations that WILL NOT have an Open API documentation

For the naming of these documentation folders make sure that the folder's name [productName] is human readable since the name that you put in is what will be used as a title

"Petstore" ✅

"Petstore - V2" ✅

"petstore_latest_doc" ❌

"petstoreLatestDoc" ❌

And same thing for the documentation markdown files .md/.mdx you can change the title that will be displayed inside the markdown files, more on that in the Adria dev portal documentation creation guide.

Naming For documentations that WILL have an Open API documentation

For the naming of these documentation folders make sure that the folder's name [productName] must be the same as it's Open Api Specification YAML file that's in the swaggar repository and instead of the Dash ( - ) ❌ seperator you must instead only use an Underscore ( _ ) ✅ as a separator and without the version suffix more on versionning down below.

"digital_marketing_service_swagger" ✅

"digital-marketing-service-swagger" ❌

"digital marketing service swagger" ❌

"digitalMarketingServiceSwagger" ❌

You can change the title that will be displayed inside the markdown file since an underscore seperated file is not human readable to do that you must create an md/mdx file that has the name index.mdx for example :

documentation
├── [productName]           <-- PARENT folder
│   └── [productName]       <-- CHILD folder
│       └── index.mdx
└── README.md

And then inside the index.mdx file you must add this block to the top of the file :

---
sidebar_label: [HUMAN READABLE TITLE FOR SIDEBAR]
---

# [HUMAN REDABLE TITLE]

...CONTENT OF MDX FILE...

For the documentation markdown files .md/.mdx you can use Human readable names with Space ( ) as seperator.

Folder tree

The folder that contains the documentation [productName] needs to be inside a folder that has the same name which we will call the PARENT folder also [productName], while the folder containing the actually documentation will be referenced as CHILD folder.

We did this so we can manage versions easily by simple changing the CHILD folder's name to [productName] - V1 for example and the PARENT will house all the different versions.

documentation
├── [productName]               <-- PARENT folder
│   ├── [productName]           <-- CHILD folder
│   │   └── doc.mdx
│   └── [productName] - V1      <-- CHILD folder
│       └── doc.mdx
└── README.md

Adding new documentation

In order to add a new documentation you must follow these steps :

1. Let's consider your documentation is about a [productName]

2. If this product has or is going to have a REST API Documentation as well you need to make sure that the [productName] is the same in the OPEN API YAML file too ! The directory is called openapi-yaml

site
├── docs
├── i18n
├── openapi-yaml
│   ├── [productName]__[version].yaml
│   ├── petstore__2.0.0.yaml
│   └── README.md
│
├── src
├── static
...

3. The [productName] must have a parent folder that has the same name and file tree should be something like this :

docs
├── api
└── documentation
    ├── [productName]
    │   └── [productName]
    │       └── doc.mdx
    ├── petstore
    │   └── petstore
    │       └── intro.mdx
    └── README.md

Versioning

If a product called [productName] needs it's documentation to be versioned you can do this :

• Before replacing the [productName] CHILD folder take the initial already existing [productName] CHILD folder rename it to [productName] - V[version] and now place the new version of the docs with the name [productName] and you should have something like this :

docs
├── api
└── documentation
    ├── [productName] <-- NOT THIS ONE (parent)
    │   ├── [productName] <-- THIS ONE (NEW DOCS)
    │   │   └── doc.md
    │   └── [productName] - V[version] <-- (OLD DOCS)
    │       └── doc.md
    ├── petstore
    │   ├── petstore
    │   │   └── intro.md
    │   └── petstore - V1   <-- THIS ONE (NEW DOCS)
    │       └── intro.md
    └── README.md

Removing a documentation

To remove a product's documentation you need to simply remove the concerned [productName] PARENT folder or if it's a version of a product's documentation you need to simply remove the concerned [productName]/[productName] - V[version] CHILD folder and then rename the versions if needed.