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

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

1. Install MkDocs

pip install mkdocs

2. Install TechDocs core plugin

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

pip install mkdocs-techdocs-core

For additional plugins, see the TechDocs Plugins Overview.

3. Install TechDocs CLI (recommended)

The TechDocs CLI helps you build and serve documentation locally, mimicking the Harness IDP environment:

npm install -g @techdocs/cli

---

Local development workflow

Step 1: Navigate to documentation directory

Navigate to the directory containing your documentation files:

cd /path/to/docs

---

Step 2: Serve documentation locally

You have two options for serving documentation locally:

Option 1: Using MkDocs (basic)

Serve your documentation using the standard MkDocs server:

mkdocs serve

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

REQUIREMENTS

This command requires an mkdocs.yml file in your documentation directory.

---

Option 2: Using TechDocs CLI (recommended)

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

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:

techdocs-cli serve -v

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

CUSTOMIZATION

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

---

Step 3: Iterate and test

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

Plugin errors

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)

---

Render issues

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

Symptoms:

• Build fails or produces warnings

• Documentation does not generate properly

Solutions:

Run a clean build to identify issues:

mkdocs build --clean

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

---