Skip to main content

Configure TechDocs Locally

Last updated on

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

Prerequisites​

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.

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.

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 (see TechDocs Plugins)

Rendering 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 doesn't 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.