Creating Tool Detail Pages

Guide for AI assistants to auto-generate tool detail pages for the Docusaurus website.

When to Create a Tool Page

Create a tool detail page when:

1. A new install script is added to .devcontainer/additions/
2. The tool is commonly used and would benefit from detailed documentation
3. The user requests comprehensive documentation for a specific tool

Page Location

Tool pages go in: website/docs/tools/

Name the file after the tool's ID (from SCRIPT_ID), e.g.:

• dev-python → python.md
• tool-azure-ops → azure-ops.md
• dev-php-laravel → php-laravel.md

Template

Use this template for new tool pages:

---
title: [Tool Name]
sidebar_position: [number]
---

# [Tool Name]

[One paragraph description of what the tool provides]

## What Gets Installed

### [Category: Packages/CLI Tools/Runtime]

| [Package/Tool] | Description |
|----------------|-------------|
| `name` | What it does |

:::note
[Any important notes about prerequisites or base image inclusions]
:::

### VS Code Extensions

| Extension | Description |
|-----------|-------------|
| Extension Name (extension.id) | What it does |

## Installation

Install via the interactive menu:

\`\`\`bash
dev-setup
\`\`\`

Or install directly:

\`\`\`bash
.devcontainer/additions/[script-name].sh
\`\`\`

To uninstall:

\`\`\`bash
.devcontainer/additions/[script-name].sh --uninstall
\`\`\`

## How to Use

[Key commands and usage patterns]

## Example Workflows

### [Workflow Name]

[Step-by-step example]

## Troubleshooting

### [Common Issue]

[Solution]

## Documentation

- [Link Name](url)

Information Sources

Extract information from the install script:

1. Metadata section (lines 10-25):

   • SCRIPT_ID - Use for file naming
   • SCRIPT_NAME - Use for page title
   • SCRIPT_DESCRIPTION - Use for intro paragraph

2. Package arrays:

   • PACKAGES_SYSTEM - System packages
   • PACKAGES_NODE - npm packages
   • PACKAGES_PYTHON - pip packages
   • PACKAGES_PWSH - PowerShell modules
   • EXTENSIONS - VS Code extensions

3. Post-installation message (post_installation_message function):

   • Quick start commands
   • Documentation links
   • Version information

Best Practices

1. Be Practical: Focus on common use cases
2. Include Examples: Show actual commands users will run
3. Note Prerequisites: What's already in base image vs. what's installed
4. Add Troubleshooting: Common issues and solutions
5. Link Official Docs: Always include links to official documentation

Sidebar Position

Use these ranges for sidebar_position:

• Development Tools (Python, TypeScript, etc.): 1-10
• AI Tools (Claude Code, etc.): 11-15
• Cloud Tools (Azure, API, etc.): 16-25
• Infrastructure Tools (Kubernetes, IaC, etc.): 26-35

Example: Extracting from Script

Given this script metadata:

SCRIPT_ID="dev-python"
SCRIPT_NAME="Python Development Tools"
SCRIPT_DESCRIPTION="Adds ipython, pytest-cov, and VS Code extensions for Python development"

PACKAGES_PYTHON=(
    "ipython"
    "pytest-cov"
    "python-dotenv"
)

EXTENSIONS=(
    "Python (ms-python.python) - Python language support"
    "Pylance (ms-python.vscode-pylance) - Python language server"
)

Create website/docs/tools/python.md with:

• Title: "Python Development"
• File: python.md
• Packages table listing ipython, pytest-cov, python-dotenv
• Extensions table listing Python and Pylance

Updating Existing Pages

When an install script is updated:

1. Check if packages were added/removed
2. Check if extensions were changed
3. Check if post_installation_message has new quick start commands
4. Update the corresponding tool page

Linking from Tools Index

The tools/index.md file is auto-generated by dev-docs. It links to tools-details.md for all tools.

For tools with detailed manual pages, consider adding a note in the index pointing to the full documentation.