How to write documentation

Run the project locally

Prerequisites:

• Node.js 18 or later
• Git

Steps:

git clone https://github.com/Spaarkly-srl/ARS_knowledge_base.git
cd ARS_knowledge_base
git checkout dev   # work on the development branch
npm install        # or: npm ci
npm start          # starts Docusaurus on http://localhost:3000

Quick Guide: Creating Sections and Managing Access

1) Where to place the files

• Active version folder (example): versioned_docs/version-1.0.0/
• Top‑level sections available (examples): getting-started/, user-guides/, integrations/, faq/, developer-docs/
• The rules in this guide apply to any section. In the examples below we’ll use developer-docs/Example just as a model — replace it with the section you need.
• Note specific to Developer Docs: do not place an _category_.json at the root of developer-docs/ if you don’t want the “Developer Docs” label duplicated in the sidebar. For other areas you may keep a root _category_.json if you want a section landing page (generated index).

2) Creating a macro-section (visible in the sidebar)

• Create a folder, e.g. developer-docs/Example/
• Inside it, add a _category_.json with label, order and generated index:

{
  "label": "Example",
  "position": 1,
  "link": { 
    "type": "generated-index",
    "description": "Description of the example section",
    "slug": "/main-section/example-section" 
  }
}

• Add the .md/.mdx files inside the folder.

3) Adding pages and ordering them

Each page can define its position in the section using sidebar_position in the frontmatter:

---
title: Example Introduction
description: Description of the section (optional)
sidebar_position: 1
---
Content…

4) Creating subsections

Create subfolders with their own _category_.json. Minimal base structure:

developer-docs/
└── your-section/
    ├── _category_.json
    ├── intro.md
    └── sub-section/
        ├── _category_.json
        └── page-1.md

Example _category_.json for a subsection:

{ 
  "label": "Your Section", 
  "position": 1, 
  "link": { 
    "type": "generated-index",
    "description": "Description of Your Section",
    "slug": "/main-section/your-section"
  } 
}

Notes:

• Each folder that must appear in the sidebar needs its own _category_.json.
• Use position to order sibling sections; inside a section, pages can set sidebar_position in frontmatter.

5) Navbar and sidebar

• Navbar: already configured in docusaurus.config.js to point to the developerDocsSidebar.
• Sidebar: is “autogenerated” from sidebars.js, so it follows the folder structure + _category_.json + sidebar_position.
• You do not need to modify the config to add sections: simply create folders and files as described above.

6) Restricting content visibility

Important: to use the MDX components shown below, the page must be saved with the .mdx extension (not .md). Otherwise, the build will fail because MDX elements are not parsed in .md files. For authenticated users only (inline login):

<AuthenticatedOnly>
  Content visible only to logged-in users
</AuthenticatedOnly>

For specific roles only:

<DeveloperOnly>
  Content restricted to technical roles
</DeveloperOnly>

To protect an entire area/path (centralised): In src/theme/DocPage/index.js there is already a wrapper that protects some sections. To extend this to Developer Docs:

<AuthContent requiredRole="developer">
  <DocItem {...props} />
</AuthContent>

Visibility of navbar items (UX): Already handled by NavbarManager + CSS: the classes user-can-access-developer / user-can-access-clients are added after login and display the correct items. ⚠️ This does not replace page protection.

7) Useful conventions

• A macro-section = a folder with _category_.json
• Subsections = subfolders with their own _category_.json
• Use position in categories to order macro-sections
• Use sidebar_position in the file frontmatter to order pages
• For a section index page, use {"type": "generated-index"} in _category_.json

8) Complete example “Example”

1. Create: versioned_docs/version-1.0.0/developer-docs/Example/

2. Add _category_.json:

{
  "label": "Example",
  "position": 1,
  "link": { 
    "type": "generated-index",
    "description": "Description of the section",
    "slug": "/name-main-section/name-section" 
  }
}

3. Add authentication.md and errors.md:

<!-- authentication.md -->
---
title: Example Authentication
sidebar_position: 1
---
<AuthenticatedOnly>
  Content restricted to authenticated users
</AuthenticatedOnly>

<!-- errors.md -->
---
title: Example Error Handling
sidebar_position: 2
---
<DeveloperOnly>
  Technical roles only
</DeveloperOnly>