Documentation

Witboost provides two ways to document entities, each serving different audiences and contexts:

Builder Documentation: Technical documentation displayed in the Builder module for any entity type (Templates, Systems, Components, etc.), aimed at developers and technical users
Marketplace Documentation: Business-oriented documentation displayed in the Marketplace, aimed at end users and business stakeholders. This documentation is only available for products and consumables (e.g., Output Ports) that are visible in the Marketplace

Both documentation types can coexist for entities that support them, allowing you to provide tailored content for different audiences.

Builder Documentation

Builder documentation is intended for technical users who need detailed information about implementation, architecture, and development guidelines. This documentation is displayed in the Builder interface when users view the entity.

Configuration

Create a mkdocs.yml file at the same level of the catalog-info.yaml of the entity with the following content:

site_name: 'example-docs'
nav:
  - Home: index.md

plugins:
  - techdocs-core

Update your entity's catalog-info.yaml by adding the following annotation:

metadata:
  annotations:
    backstage.io/techdocs-ref: dir:.

The backstage.io/techdocs-ref annotation is used to download the documentation source files for generating the entity's technical documentation site.

Create a /docs folder at the same level of the catalog-info.yaml of the entity with at least an index.md file in it. If you add more markdown files, make sure to update the nav section in the mkdocs.yml file to get proper navigation for your documentation.

note

Although docs is a popular directory name for storing documentation, it can be renamed to something else and configured in mkdocs.yml. See https://www.mkdocs.org/user-guide/configuration/#docs_dir

The docs/index.md can for example have the following content:

# Technical Documentation

This is the technical documentation for developers.

## Architecture

Detailed architecture overview...

## Development Guidelines

Guidelines for contributing to this component...

Marketplace Documentation

Marketplace documentation is intended for business users and should focus on business value, use cases, and how to consume or utilize the asset. This documentation is displayed in a dedicated tab in the Marketplace when users browse available assets.

Configuration

Update your entity's catalog-info.yaml by adding the following annotation:

metadata:
  annotations:
    witboost.com/end-user-docs-ref: dir:./end-user-docs

The witboost.com/end-user-docs-ref annotation must reference a directory within the same repository using the dir: prefix. The path should point to the folder containing your end-user documentation.

note

The folder name end-user-docs is just a suggested convention. You can use any folder name that suits your needs (e.g., marketplace-docs, business-docs, etc.), as long as it matches the path specified in the witboost.com/end-user-docs-ref annotation.

Inside your chosen folder (e.g., /end-user-docs), create a mkdocs.yml file:

site_name: 'marketplace-docs'
nav:
  - Home: index.md

plugins:
  - techdocs-core

Create a /docs subfolder inside your end-user-docs folder (i.e., end-user-docs/docs/) with your business-oriented markdown content. For example, create end-user-docs/docs/index.md:

# Product Overview

This data product provides customer analytics insights.

## What You Can Do

- Access customer segmentation data
- Analyze purchase patterns
- Generate business reports

## How to Use

1. Navigate to the Marketplace
2. Request access to this asset
3. Follow the integration guide...

## Business Value

This asset helps you understand customer behavior and improve marketing campaigns.

Content Guidelines

When writing Marketplace documentation:

Focus on business value and use cases rather than technical implementation
Use plain language accessible to non-technical users
Include step-by-step guides for consuming the asset
Highlight key features and capabilities
Provide examples of insights or outputs users can expect
Avoid technical jargon and implementation details

Using Both Documentation Types

You can provide both technical and business documentation for the same entity by including both annotations in your catalog-info.yaml:

metadata:
  annotations:
    backstage.io/techdocs-ref: dir:.
    witboost.com/end-user-docs-ref: dir:./end-user-docs

Recommended Repository Structure

When using both documentation types, the recommended structure is:

your-repository/
├── mkdocs.yml                    # Configuration for Builder docs
├── docs/                         # Technical documentation
│   ├── index.md
│   ├── architecture.md
│   └── development.md
├── end-user-docs/                # Marketplace documentation folder
│   ├── mkdocs.yml                # Configuration for Marketplace docs
│   └── docs/                     # Business documentation
│       ├── index.md
│       ├── overview.md
│       └── how-to-use.md
└── catalog-info.yaml

This structure allows you to:

Maintain separate navigation structures for each audience
Use different MkDocs configurations or plugins
Keep technical and business content clearly separated
Update documentation independently based on audience needs

tip

Each documentation type requires its own mkdocs.yml file in its respective root directory, and a /docs subfolder containing the markdown files. The Builder documentation has mkdocs.yml at the repository root, while Marketplace documentation has it inside the folder specified by the witboost.com/end-user-docs-ref annotation.

Example: Complete Entity with Both Documentation Types

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: customer-analytics-output-port
  title: Customer Analytics Output Port
  description: Provides customer segmentation and analytics data
  annotations:
    backstage.io/techdocs-ref: dir:.
    witboost.com/end-user-docs-ref: dir:./end-user-docs
spec:
  type: outputport
  lifecycle: production
  owner: analytics-team
  domain: marketing

With this configuration:

Developers accessing the component in the Builder will see technical documentation built from /docs using the root mkdocs.yml
Business users browsing the component in the Marketplace will see business-oriented documentation built from /end-user-docs/docs using /end-user-docs/mkdocs.yml

Previewing and Publishing Documentation

Witboost handles documentation building differently for each documentation type:

Builder Documentation: Built on-demand when first accessed, then cached. The cache is automatically invalidated and the documentation rebuilt when repository changes are detected
Marketplace Documentation: Built when a snapshot is created or updated, and published when a deployment is executed to the Marketplace.

Despite this automatic handling, you may want to preview your documentation locally during development or publish it independently using CI/CD pipelines for testing or external hosting purposes.

Local Preview

To preview your documentation locally, you need to install the required dependencies and serve the documentation using MkDocs.

Prerequisites:

Python 3.8 or higher: Ensure Python is installed on your system. Check by running:
```
python --version
```

Create and activate a virtual environment: It's recommended to use a virtual environment to avoid conflicts with other Python packages:

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

Install mkdocs-techdocs-core: Install version 1.3.2, which is the same version used by Witboost to ensure compatibility:
```
pip install mkdocs-techdocs-core==1.3.2
```

Preview Builder Documentation:

Navigate to the root of your repository where the mkdocs.yml file is located and run:

mkdocs serve

This will start a local development server, typically at http://127.0.0.1:8000, where you can preview your technical documentation. The server will automatically reload when you make changes to your markdown files.

Preview Marketplace Documentation:

Navigate to the folder containing your Marketplace documentation (e.g., /end-user-docs) and run:

cd end-user-docs
mkdocs serve

This will serve your business-oriented documentation at http://127.0.0.1:8000.

tip

If you need to preview both documentation types simultaneously on different ports, specify a custom address for one of them:

# Terminal 1 - Builder docs on default port
mkdocs serve

# Terminal 2 - Marketplace docs on custom port
cd end-user-docs
mkdocs serve --dev-addr=127.0.0.1:8001

Publishing with GitLab CI/CD and GitLab Pages

If your repository is hosted on GitLab and you want to automatically build and publish your documentation using GitLab Pages, you can set up a CI/CD pipeline.

Repository Structure:

The structure would be:

your-repository/
├── .gitlab-ci.yml                # GitLab CI/CD configuration
├── mkdocs.yml                    # Builder docs configuration
├── docs/                         # Technical documentation
├── end-user-docs/                # Marketplace documentation folder
│   ├── mkdocs.yml                # Marketplace docs configuration
│   └── docs/                     # Business documentation
└── catalog-info.yaml

GitLab CI/CD Configuration:

Create or update your .gitlab-ci.yml file in the root of your repository with the following content:

image: python:3.8

variables:
  # Specify which documentation to publish (builder or marketplace)
  DOCS_TYPE: "marketplace"  # Change to "builder" if needed

stages:
  - build
  - deploy

# Build the documentation
build-docs:
  stage: build
  before_script:
    - pip install mkdocs-techdocs-core==1.3.2
  script:
    # Build based on DOCS_TYPE variable
    - |
      if [ "$DOCS_TYPE" = "marketplace" ]; then
        cd end-user-docs
        mkdocs build --site-dir ../public
      else
        mkdocs build --site-dir public
      fi
  artifacts:
    paths:
      - public
    expire_in: 1 hour
  only:
    - main
    - master

# Deploy to GitLab Pages
pages:
  stage: deploy
  dependencies:
    - build-docs
  script:
    - echo "Deploying to GitLab Pages..."
  artifacts:
    paths:
      - public
  only:
    - main
    - master

Pipeline Explanation:

Image: Uses a Python 3.8 Docker image as the base environment
Variables: Defines which documentation type to publish. Set to "builder" or "marketplace" to choose which documentation to deploy.
build-docs job:
- Installs the required mkdocs-techdocs-core plugin
- Builds the documentation based on the DOCS_TYPE variable
- For marketplace docs, navigates to the end-user-docs folder and builds the site to the ../public directory
- For builder docs, builds directly from the repository root
- Stores the generated public folder as an artifact
pages job:
- GitLab's special job for Pages deployment
- Takes the public artifact from the previous job
- Automatically deploys to GitLab Pages

Publishing Both Documentation Types:

If you want to publish both documentation types on GitLab Pages (e.g., Builder docs at the root path and Marketplace docs at /marketplace), you can modify the .gitlab-ci.yml:

image: python:3.9

stages:
  - build
  - deploy

build-docs:
  stage: build
  before_script:
    - pip install mkdocs-techdocs-core==1.3.2
  script:
    # Build Builder documentation
    - mkdocs build --site-dir public
    # Build Marketplace documentation
    - cd end-user-docs
    - mkdocs build --site-dir ../public/marketplace
  artifacts:
    paths:
      - public
    expire_in: 1 hour
  only:
    - main
    - master

pages:
  stage: deploy
  dependencies:
    - build-docs
  script:
    - echo "Deploying to GitLab Pages..."
  artifacts:
    paths:
      - public
  only:
    - main
    - master

With this configuration:

Builder documentation will be available at https://your-pages-url/
Marketplace documentation will be available at https://your-pages-url/marketplace/

Accessing Your Published Documentation:

Once the pipeline completes successfully, you can access it opening the link present in Deploy > Pages section.

Documentation Types Comparison

Aspect	Builder Documentation	Marketplace Documentation
Audience	Developers, technical users	Business users, data consumers
Location	Builder interface (all views)	Marketplace tab
Annotation	`backstage.io/techdocs-ref`	`witboost.com/end-user-docs-ref`
Availability	All entity types	Systems and consumable Components only
Build Trigger	On-demand (first access)	Snapshot creation/deployment
Update Method	Automatic on repo changes	Requires new snapshot + deployment
Content Focus	Technical details, architecture	Business value, use cases
Typical Sections	Architecture, API docs, dev guides	Overview, how-to, business value
Configuration File	`mkdocs.yml` at repo root	`mkdocs.yml` in end-user-docs folder (e.g., `end-user-docs/mkdocs.yml`)
index.md Path	`/docs/index.md`	`/end-user-docs/docs/index.md`

Troubleshooting

Builder Documentation Issues

Documentation not appearing in Builder:

Verify the backstage.io/techdocs-ref annotation is present and correct in catalog-info.yaml
Ensure mkdocs.yml exists at the repository root
Check that /docs/index.md exists and contains valid markdown
Wait a few minutes for the cache to refresh after repository changes
Refresh the entity from the Administration Panel

Build errors when accessing documentation:

Validate your mkdocs.yml syntax
Ensure all markdown files referenced in the nav section exist
Check that relative links in markdown files are correct

Marketplace Documentation Issues

Documentation not appearing in Marketplace:

Confirm the entity is a System or consumable Component (e.g., Output Port)
Verify the witboost.com/end-user-docs-ref annotation path is correct
Ensure a snapshot has been created after adding the documentation
Check that the snapshot has been deployed to the Marketplace
Verify the folder structure: end-user-docs/mkdocs.yml and end-user-docs/docs/index.md

Documentation not updating after changes:

Create a new snapshot to capture the latest documentation
Deploy the new snapshot to the Marketplace
Clear your browser cache if changes still don't appear

Local Preview Issues

mkdocs serve fails to start:

Verify Python version is 3.8 or higher: python --version
Check mkdocs-techdocs-core is installed: pip list | grep mkdocs
Ensure you're in the correct directory (where mkdocs.yml is located)
Validate mkdocs.yml syntax using an online YAML validator

Port already in use:

Use a different port: mkdocs serve --dev-addr=127.0.0.1:8001
Or stop the process using the port: lsof -ti:8000 | xargs kill (Mac/Linux)

Images or assets not displaying:

Check file paths are relative to the markdown file
Ensure assets are inside the /docs folder
Verify file names match exactly (case-sensitive on some systems)

CI/CD Pipeline Issues

GitLab Pages build failing:

Check pipeline logs for specific error messages
Verify mkdocs-techdocs-core==1.3.2 is installed correctly
Ensure the public directory is generated before deployment
Confirm branch names match the pipeline configuration (main or master)

Documentation deployed but not accessible:

For GitLab: Check Deploy > Pages for the correct URL
Wait a few minutes for DNS propagation

Builder Documentation​

Configuration​

Marketplace Documentation​

Configuration​

Content Guidelines​

Using Both Documentation Types​

Recommended Repository Structure​

Example: Complete Entity with Both Documentation Types​

Previewing and Publishing Documentation​

Local Preview​

Publishing with GitLab CI/CD and GitLab Pages​

Documentation Types Comparison​

Troubleshooting​

Builder Documentation Issues​

Marketplace Documentation Issues​

Local Preview Issues​

CI/CD Pipeline Issues​

Builder Documentation

Configuration

Marketplace Documentation

Configuration

Content Guidelines

Using Both Documentation Types

Recommended Repository Structure

Example: Complete Entity with Both Documentation Types

Previewing and Publishing Documentation

Local Preview

Publishing with GitLab CI/CD and GitLab Pages

Documentation Types Comparison

Troubleshooting

Builder Documentation Issues

Marketplace Documentation Issues

Local Preview Issues

CI/CD Pipeline Issues