Project Folder Structure

Run theneo export --dir ./docs and you get a clean, version-controllable folder of Markdown. Here’s what’s inside.

The folder layout

Every section of your docs is a folder containing exactly two files: an index.md (the rendered content) and a section.json (its API and widget metadata). A single theneo.json at the root defines the navigation. Nesting folders creates nested sections in the sidebar.

 
  your-documentation/
├── theneo.json
├── introduction/
│   ├── index.md
│   └── section.json
├── getting-started/
│   ├── index.md
│   └── section.json
└── api-reference/
    ├── index.md
    ├── section.json
    └── endpoints/
        └── create-customer/
            ├── index.md
            └── section.json

Rules: every folder is one section and must contain both index.md and section.json. The folder name becomes the section’s slug (lowercase, hyphenated) and must match what’s declared in theneo.json.

theneo.json — the manifest

The root theneo.json defines your project and assembles the sidebar. Its key fields:

• id, name, baseUrl — project identity and the base URL used in code samples.
• isSinglePage — render as one continuous page (true) or a navigable multi-page site (false).
• sections — the ordered tree of sections (the sidebar).
• tabs — the top-level tabs that group sections.

Each section object looks like this:

 
  {
  "name": "Introduction",
  "slug": "introduction",
  "children": [],
  "icon": null,
  "isHeader": false,
  "externalPageLink": "",
  "isNewTab": false
}

• name — the sidebar label. slug — must match the folder on disk.
• children — nested section objects (empty for a leaf).
• isHeader — true for a group label with no page of its own.
• externalPageLink / isNewTab — link the entry to an external URL instead of an internal page.

Each tab object lists which top-level section slugs appear under it:

 
  {
  "title": "Documentation",
  "slug": "documentation",
  "sections": ["introduction", "getting-started", "api-reference"],
  "iconUrl": "",
  "svgCode": ""
}

section.json — per-section metadata

Every section folder needs a section.json — even plain documentation pages, which use the default below. Theneo treats it as a no-op and just renders the index.md.

 
  {
  "endpoints": { "method": "GET", "path": "" },
  "request": null,
  "responses": [],
  "showBaseUrl": false,
  "showLanguageBox": false,
  "showRequestDescription": true,
  "showResponseDescription": true,
  "errorCodes": [],
  "statusCodes": [],
  "dataExample": [],
  "endpointSummary": []
}

When a section documents an API endpoint, populate the relevant fields — endpoints.method and endpoints.path (e.g. /v1/customers/{id}), the request body, responses, errorCodes, statusCodes, and toggles like showBaseUrl and showLanguageBox.

index.md — your content

Standard Markdown plus Theneo’s widgets. If your project uses tabs, start each index.md with a tab marker comment whose slug matches a tab in theneo.json:

 
  <!-- tab:documentation -->

# Introduction

Welcome to the API documentation...

The marker is an HTML comment, so it never renders. A section can belong to one tab only — its slug appears in exactly one tab’s sections array.

The round-trip workflow

Automate the round-trip with GitHub Sync, and see the commands in Docs-as-Code with Markdown.