> 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

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/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/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.

***