mkdocs-snippet-lens Extension Examples

This project is an example of using the mkdocs-snippet-lens VS Code extension. The extension enhances the MkDocs development experience by providing in-editor features for working with PyMdown Extensions' snippets extension.

What is mkdocs-snippet-lens?

The mkdocs-snippet-lens extension provides:

• Clickable links to snippet files (Cmd/Ctrl+click to open)
• Inline previews showing snippet content on hover
• Ghost text previews displaying a single-line preview after the snippet reference
• Error diagnostics highlighting missing snippet files with red squiggles

Prerequisites

• Python 3.8+ - Required to run MkDocs
• Visual Studio Code - The extension runs in VS Code
• mkdocs-snippet-lens extension - Automatically installed when you open this workspace in VS Code (configured in .vscode/extensions.json)

Setup

1. Clone this repository:

   git clone <repository-url>
   cd mkdocs-snippet-lens-examples

2. Create a virtual environment (recommended):

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Open the project in VS Code:

   code .

   When you open the workspace, VS Code will prompt you to install the recommended mkdocs-snippet-lens extension automatically (configured in .vscode/extensions.json). Click "Install" when prompted.

Running the Example

1. Start the MkDocs development server:

   mkdocs serve

2. View the site:

   • Open your browser to http://127.0.0.1:8000/
   • You'll see the examples rendered with the snippet content

3. Explore the extension features:

   • Open docs/index.md in VS Code
   • Notice the underlined snippet file references
   • Hover over docs/examples/ex01.go to see a preview
   • Cmd/Ctrl+click on the filename to open it
   • See the ghost text preview displayed inline
   • Notice the red squiggle under docs/examples/ex02.go (file doesn't exist)

Learn More

• mkdocs-snippet-lens Extension
• PyMdown Extensions - Snippets
• MkDocs Documentation
• Material for MkDocs

License

This example project is provided for demonstration purposes.