Markdown support

Theneo provides robust markdown support both within the editor and through CLI-based markdown imports, enabling flexible documentation creation and management workflows.

In-Editor Markdown Support

Standard Markdown Formatting

Theneo's editor supports all standard markdown formatting including:

• Headers (H1-H6)
• Bold and italic text
• Inline code and code blocks with syntax highlighting
• Lists (ordered and unordered)
• Links and images
• Tables
• Blockquotes
• Horizontal rules

Theneo Custom Widgets

Beyond standard markdown, Theneo provides custom widgets that enhance API documentation with interactive elements. These widgets enable rich content presentation directly within your markdown files.

Code Blocks with Enhanced Features

 
<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"bash","label":"Bash"}'>
  <CodeLine>npm install -g @theneo/cli@latest</CodeLine>
</CodeBlock>

Interactive Accordions

 
<Accordion attributes='{"style":{"width":"100%"}}'>
<AccordionItem title="Authentication" iconUrl="">
  <p>Your authentication content here</p>
</AccordionItem>
</Accordion>

Callout Blocks

 
<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%"}}'>
  Important information for your users
</Callout>

These widgets can be combined with standard markdown to create comprehensive, interactive API documentation that enhances developer experience.

Importing Markdown Folders

Theneo CLI provides powerful capabilities for managing documentation through markdown files, enabling version control and collaborative workflows.

Installation

 
npm install -g @theneo/cli@latest

Project Structure Requirements

To import markdown folders into Theneo, your project must follow a specific structure:

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
│       └── get-customer/
│           ├── index.md
│           └── section.json 

Configuration Files

theneo.json - Project Structure Definition

The theneo.json file defines the overall structure and hierarchy of your documentation:

 
{
  "name": "Your API Documentation",
  "baseUrl": "https://api.yourdomain.com",
  "sections": [
    {
      "name": "Introduction",
      "slug": "introduction",
      "icon": "6",
      "isHeader": false
    },
    {
      "name": "Getting Started",
      "slug": "getting-started",
      "isHeader": true,
      "children": [
        {
          "name": "Authentication",
          "slug": "getting-started/authentication",
          "icon": "5"
        }
      ]
    },
    {
      "name": "API Reference",
      "slug": "api-reference",
      "isHeader": true,
      "children": [
        {
          "name": "Customer Management",
          "slug": "api-reference/customer-management",
          "children": [
            {
              "name": "Create Customer",
              "slug": "api-reference/customer-management/create-customer"
            }
          ]
        }
      ]
    }
  ]
}

section.json - API Endpoint Definition

For sections containing API endpoints, the section.json file defines request and response specifications:

 
{
  "endpoints": {
    "method": "POST",
    "path": "/customers"
  },
  "request": {
    "contentType": "application/json",
    "body": [
      {
        "name": "given_name",
        "description": "The first name of the customer",
        "isRequired": true,
        "valueType": "string",
        "value": "John"
      },
      {
        "name": "email_address",
        "description": "The email address of the customer",
        "isRequired": true,
        "valueType": "string",
        "value": "john@example.com"
      }
    ],
    "header": [
      {
        "name": "Authorization",
        "description": "Bearer token for authentication",
        "isRequired": true,
        "valueType": "string",
        "value": "Bearer <access_token>"
      }
    ]
  },
  "responses": [
    {
      "statusCode": 200,
      "description": "Successful response",
      "contentType": "application/json",
      "body": [
        {
          "name": "customer",
          "description": "The created customer object",
          "valueType": "object"
        }
      ]
    }
  ]
}

For sections without API endpoints (like introductory content), section.json can be an empty object {}.

CLI Commands for Markdown Management

Creating a New Project from Markdown

 
theneo create --dir ./your-documentation --name "API Documentation" --workspace your-workspace

Importing/Updating Existing Project

 
theneo import --dir ./your-documentation --project your-project-slug --workspace your-workspace

Exporting Project as Markdown

 
theneo export --project your-project-slug --dir ./exported-docs

Best Practices

1. Version Control: Keep your markdown documentation in Git for version tracking and collaboration
2. Consistent Structure: Maintain the required folder structure for seamless imports
3. Modular Organization: Organize endpoints logically within nested folders
4. Descriptive Names: Use clear, kebab-case slugs for sections and endpoints
5. Complete Metadata: Ensure all section.json files contain complete API specifications
6. Regular Sync: Use CI/CD pipelines to automatically sync documentation updates

Example Workflow

1. mkdir api-docs && cd api-docstouch theneo.json
2. mkdir -p api-reference/customersecho "# Customer Management API" > api-reference/customers/index.mdecho '{}' > api-reference/customers/section.json
3. theneo login --token your-api-keytheneo create --dir . --name "My API Docs" --publish
4. # Make changes to your markdown filestheneo import --dir . --project your-project-slug --publish

Advanced Features

AI-Powered Description Generation

When importing documentation, leverage AI to automatically generate or enhance descriptions:

 
theneo project create --file ./openapi.json --generate-description fill

Options:

• fill: Add descriptions where missing
• overwrite: Replace all existing descriptions
• no_generation: Skip AI generation (default)

Multi-Environment Support - Only for Enterprise accounts

Use profiles for different environments:

 
theneo login --profile production --token prod-api-key
theneo import --dir . --project api-docs --profile production

Working with Complex API Structures

For complex APIs with nested resources, organize your folder structure to mirror your API architecture:

api-reference/
├── customers/
│   ├── index.md
│   ├── section.json
│   ├── create/
│   │   ├── index.md
│   │   └── section.json
│   ├── retrieve/
│   │   ├── index.md
│   │   └── section.json
│   └── orders/
│       ├── index.md
│       ├── section.json
│       └── list/
│           ├── index.md
│           └── section.json 

This structure translates to:

• /customers - Create Customer
• /customers/{id} - Retrieve Customer
• /customers/{id}/orders - List Customer Orders

Troubleshooting

Common Issues and Solutions

1. Import fails with structure error:
   1. Verify theneo.json exists in root directory
   2. Ensure all section slugs match folder names exactly
   3. Check that each section folder contains index.md and section.json
2. API endpoints not appearing:
   1. Confirm section.json contains valid endpoint configuration
   2. Validate JSON syntax in all configuration files
   3. Ensure method and path are correctly specified
3. Markdown rendering issues:
   1. Use proper escaping for special characters
   2. Verify custom widget syntax matches documentation
   3. Test widgets individually before combining
4. Authentication errors:
   1. Confirm API key is valid: theneo login --token your-api-key
   2. Check workspace permissions
   3. Verify profile configuration if using multiple environments

Migration Guide

From Static Markdown to Theneo

If you have existing markdown documentation, follow these steps to migrate:

1. Analyze current structure: Map your existing documentation to Theneo's section hierarchy
2. Create theneo.json: Define your documentation structure
3. Reorganize files: Move markdown files into the required folder structure
4. Add section.json files: Define API endpoints where applicable
5. Test import locally: Use theneo create --dir . --name "Test Import"
6. Iterate and refine: Adjust structure based on import results

From Other Documentation Platforms

When migrating from platforms like Swagger UI, Redoc, or Postman:

1. Export OpenAPI/Swagger spec if available
2. Use Theneo's import feature: theneo project create --file openapi.json
3. Export as markdown: theneo export --project your-project --dir ./markdown
4. Customize markdown files with additional content
5. Re-import with enhancements: theneo import --dir ./markdown --project your-project

Integration with CI/CD

GitHub Actions Example

 
name: Deploy Documentation
on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '16'
      
      - name: Install Theneo CLI
        run: npm install -g @theneo/cli@latest
      
      - name: Deploy to Theneo
        env:
          THENEO_API_KEY: ${{ secrets.THENEO_API_KEY }}
        run: |
          theneo import \
            --dir ./docs \
            --project ${{ vars.THENEO_PROJECT }} \
            --workspace ${{ vars.THENEO_WORKSPACE }} \
            --publish

GitLab CI Example

 
deploy-docs:
  stage: deploy
  image: node:16
  script:
    - npm install -g @theneo/cli@latest
    - theneo login --token $THENEO_API_KEY
    - theneo import --dir ./docs --project $THENEO_PROJECT --publish
  only:
    - main
  when: manual

Conclusion

Theneo's markdown support provides a flexible, developer-friendly approach to API documentation. Whether you prefer working directly in the editor with custom widgets or managing documentation as code through the CLI, Theneo adapts to your workflow while maintaining professional, interactive documentation.

For more information and updates, visit:

• Theneo CLI GitHub Repository
• NPM Package