> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/internal-developer-portal/3.0/use-idp/software-catalog/integrate-tools/techdocs/working-with-techdocs-locally.md).

# Configure TechDocs Locally

Learn how to preview and test your TechDocs documentation locally before publishing.

Working with TechDocs locally allows you to preview changes, test plugins, and troubleshoot issues before pushing your documentation to the repository.

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

Before working with TechDocs locally, ensure you have the following installed:

#### 1. Install MkDocs <a href="#id-1-install-mkdocs" id="id-1-install-mkdocs"></a>

```sh
pip install mkdocs
```

#### 2. Install TechDocs core plugin <a href="#id-2-install-techdocs-core-plugin" id="id-2-install-techdocs-core-plugin"></a>

Install the `techdocs-core` plugin which includes all essential plugins:

```sh
pip install mkdocs-techdocs-core
```

For additional plugins, see the [TechDocs Plugins Overview](/internal-developer-portal/3.0/use-idp/software-catalog/integrate-tools/techdocs/techdocs-plugins-overview.md).

#### 3. Install TechDocs CLI (recommended) <a href="#id-3-install-techdocs-cli-recommended" id="id-3-install-techdocs-cli-recommended"></a>

The [TechDocs CLI](https://backstage.io/docs/features/techdocs/cli) helps you build and serve documentation locally, mimicking the Harness IDP environment:

```sh
npm install -g @techdocs/cli
```

***

### Local development workflow <a href="#local-development-workflow" id="local-development-workflow"></a>

#### Step 1: Navigate to documentation directory <a href="#step-1-navigate-to-documentation-directory" id="step-1-navigate-to-documentation-directory"></a>

Navigate to the directory containing your documentation files:

```sh
cd /path/to/docs
```

***

#### Step 2: Serve documentation locally <a href="#step-2-serve-documentation-locally" id="step-2-serve-documentation-locally"></a>

You have two options for serving documentation locally:

**Option 1: Using MkDocs (basic)**

Serve your documentation using the standard MkDocs server:

```sh
mkdocs serve
```

Access your documentation at `http://localhost:8000`.

{% hint style="info" %}
**REQUIREMENTS**

This command requires an `mkdocs.yml` file in your documentation directory.
{% endhint %}

***

**Option 2: Using TechDocs CLI (recommended)**

Use the TechDocs CLI to mimic the Harness IDP build process:

```sh
techdocs-cli serve
```

**Benefits:**

* Renders documentation exactly as it appears in Harness IDP
* Automatically generates `mkdocs.yml` if not present
* Better compatibility with TechDocs-specific features

**Enable verbose logging for debugging:**

```sh
techdocs-cli serve -v
```

{% hint style="warning" %}
**LIMITATIONS**

* **iFrames**: Cannot be rendered locally; they only work when hosted in Harness IDP
* **Auto-generated config**: If no `mkdocs.yml` exists, TechDocs generates a basic configuration automatically
  {% endhint %}

{% hint style="info" %}
**CUSTOMIZATION**

To customize your documentation (add plugins, modify structure, etc.), create an `mkdocs.yml` file in your docs directory.
{% endhint %}

***

#### Step 3: Iterate and test <a href="#step-3-iterate-and-test" id="step-3-iterate-and-test"></a>

1. **Edit** your Markdown files
2. **Refresh** your browser to see changes in real-time
3. **Verify** navigation, plugins, and content rendering
4. **Test** all links and embedded media

***

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

#### Plugin errors <a href="#plugin-errors" id="plugin-errors"></a>

**Symptoms:**

* "Plugin not found" or "Plugin not installed" errors
* Missing features or functionality

**Solutions:**

* Ensure all required plugins are installed: `pip install mkdocs-techdocs-core`
* Verify plugin compatibility with your MkDocs version
* Check that plugins are correctly listed in your `mkdocs.yml`
* Use `techdocs-core` instead of individual plugins (go to [TechDocs Plugins](/internal-developer-portal/3.0/use-idp/software-catalog/integrate-tools/techdocs/techdocs-plugins-overview.md))

***

#### Render issues <a href="#render-issues" id="render-issues"></a>

**Symptoms:**

* Content not displaying correctly
* Broken formatting or layout
* Missing navigation elements

**Solutions:**

* Test with both `mkdocs serve` and `techdocs-cli serve` to identify discrepancies
* Review your `mkdocs.yml` configuration for syntax errors
* Verify all Markdown files use correct syntax
* Check that image and file paths are correct

***

#### Build warnings and errors <a href="#build-warnings-and-errors" id="build-warnings-and-errors"></a>

**Symptoms:**

* Build fails or produces warnings
* Documentation does not generate properly

**Solutions:**

Run a clean build to identify issues:

```sh
mkdocs build --clean
```

Review the output for specific error messages and warnings, then address them accordingly.

***

{% @harness-feedback/feedback %}