Advanced Documentation Features

Estimated time to read: 12 minutes

Advanced MkDocs Features¶

MkDocs offers powerful features that can transform basic documentation into engaging, interactive learning experiences. In this lab, you'll master advanced MkDocs capabilities including admonitions for highlighting important information, sticky tabs for multi-language content, content includes for reusable sections, and other features that make workshop documentation more effective and maintainable.

What You'll Learn¶

In this lab, you will:

Create and customize admonitions (tips, warnings, notes) for better content organization
Implement sticky tabs for multi-language code examples and content switching
Use content includes to create reusable, maintainable documentation components
Add visual enhancements with lightbox image galleries and media integration
Configure advanced markdown extensions for rich content formatting
Optimize time-to-read calculations for better user experience

Prerequisites¶

Completion of Lab 3: Setting up MkDocs Documentation
A working MkDocs environment with the Material theme
Basic understanding of Markdown syntax
Your workshop documentation site running locally

Introduction¶

Advanced MkDocs features bridge the gap between simple documentation and engaging learning experiences. While basic Markdown serves functional needs, these enhanced features help you:

Guide attention with visually distinct callouts and warnings
Reduce cognitive load by organizing complex information clearly
Support diverse audiences with language-specific content tabs
Maintain consistency through reusable content components
Enhance engagement with interactive and media-rich elements

The key is using these features purposefully—not because they're available, but because they serve your learners' needs. In this lab, you'll learn when and how to apply each feature for maximum educational impact.

Lab Exercise¶

You'll implement and configure advanced MkDocs features, creating examples that demonstrate best practices for workshop documentation.

Step 1: Master MkDocs Admonitions¶

Admonitions are styled callout boxes that draw attention to important information. Learn to use them effectively for different types of content.

Consistency is Key

Be consistent with your admonition usage throughout your workshop documentation!

Use the same admonition type for similar content (e.g., always use "tip" for best practices)
Maintain consistent titles and messaging patterns
Stick to 3-4 core admonition types to avoid overwhelming readers
Create a style guide for your team defining when to use each type

Consistent admonition usage significantly improves the reader's experience by creating predictable information patterns they can learn to recognize quickly.

Create a new file called advanced-features-demo.md in your docs/docs/en/ folder:

Markdown
# Advanced MkDocs Features Demo

This page demonstrates advanced features for engaging workshop documentation.

## Admonition Examples

### Information and Tips

Add the most useful admonition types:

Markdown
### Essential Admonitions

!!! tip "Best Practice"
    Tips provide helpful shortcuts and expert insights that make learners more effective.

!!! warning "Common Pitfall"
    Warnings help prevent errors and highlight potential issues before they occur.

!!! example "Try This"
    Example admonitions highlight hands-on activities and exercises.

??? info "Click to Expand: Additional Details"
    Collapsible admonitions are perfect for optional information that might overwhelm beginners but could be useful for advanced users.

Test your admonitions by viewing them in your MkDocs site to ensure proper styling.

Step 2: Implement Sticky Tabs for Multi-Format Content¶

Sticky tabs allow learners to choose their preferred format (programming language, operating system, etc.) and maintain that choice across your entire documentation.

Add sticky tab examples to your demo file:

Markdown
## Sticky Tabs for Multiple Formats

### Code Examples by Language

These tabs will "stick" - if a user selects Python here, Python will be
selected automatically on other tabbed sections throughout the site.

=== "Python"
    ```python
    def create_workshop_content():
        """Create engaging workshop documentation."""
        content = {
            "title": "My Workshop",
            "duration": "2 hours",
            "audience": "developers"
        }
        return content

    # Call the function
    workshop = create_workshop_content()
    print(f"Created: {workshop['title']}")
    ```

=== "JavaScript"
    ```javascript
    function createWorkshopContent() {
        // Create engaging workshop documentation
        const content = {
            title: "My Workshop",
            duration: "2 hours", 
            audience: "developers"
        };
        return content;
    }

    // Call the function
    const workshop = createWorkshopContent();
    console.log(`Created: ${workshop.title}`);
    ```

=== "C#"
    ```csharp
    public class WorkshopContent
    {
        public string Title { get; set; }
        public string Duration { get; set; }
        public string Audience { get; set; }

        public static WorkshopContent Create()
        {
            return new WorkshopContent
            {
                Title = "My Workshop",
                Duration = "2 hours",
                Audience = "developers"
            };
        }
    }

    // Usage
    var workshop = WorkshopContent.Create();
    Console.WriteLine($"Created: {workshop.Title}");
    ```

Add platform-specific instructions using tabs:

Markdown
### Installation by Operating System

=== "Windows"
    ```cmd
    winget install Python.Python.3.11
    pip install mkdocs-material
    ```

=== "macOS"
    ```bash
    brew install python@3.11
    pip3 install mkdocs-material
    ```

=== "Linux"
    ```bash
    sudo apt install python3.11 python3-pip
    pip3 install mkdocs-material
    ```

Sticky Tabs

Once a user selects their platform (e.g., Windows), that choice will persist across all tabbed sections throughout your documentation site.

Step 3: Create Reusable Content with Includes¶

Content includes allow you to write once and reuse content across multiple pages, ensuring consistency and easier maintenance.

Create include files in the docs/docs/includes/en/ directory:
Bash
1
cd docs/docs/includes/en/

Create common-prerequisites.md:

Markdown
## Prerequisites

Before starting this lab, ensure you have:

- [ ] Completed all previous labs in sequence
- [ ] A working MkDocs development environment
- [ ] Python 3.7+ installed and accessible via command line
- [ ] A text editor or IDE configured for Markdown editing
- [ ] Approximately 45-60 minutes available for hands-on practice

!!! tip "Preparation Time"
    Take a few minutes to verify these prerequisites before beginning.
    This will help you avoid interruptions during the hands-on exercises.

Create troubleshooting-footer.md:

Markdown
## Need Help?

If you encounter issues during this lab:

1. **Check the troubleshooting section** above for common solutions
2. **Review the error messages** carefully for specific guidance  
3. **Verify prerequisites** are met and properly configured
4. **Restart your development server** if content isn't updating
5. **Ask for assistance** during instructor-led sessions

!!! info "Community Support"
    For self-guided learners, consider joining our community forum
    where you can ask questions and help other participants.

Create workshop-footer.md:

Markdown
---

**Workshop Series:** Documentation Best Practices | 
**Estimated Reading Time:** {{ page.meta.reading_time }} minutes |
**Last Updated:** {{ page.meta.revision_date }}

!!! question "Feedback Welcome"
    Help us improve this workshop by sharing your experience and suggestions.
    Your feedback helps us create better learning materials for everyone.

Use includes in your demo file:

Markdown
## Using Content Includes

You can include reusable content snippets using the include-markdown plugin:

### Standard Prerequisites Section
## Prerequisites

Before starting this workshop, ensure you have:

- **Python 3.7 or higher** installed on your system
- **Git** for version control
- A **GitHub account** for repository hosting
- A **text editor** or IDE of your choice (VS Code recommended)
- **Basic familiarity** with Markdown syntax
- **Command line/terminal** access on your system

### System Requirements

- Operating System: Windows 10/11, macOS 10.14+, or Ubuntu 18.04+
- RAM: Minimum 4GB (8GB recommended)
- Storage: At least 1GB free space
- Internet connection for package downloads and deployment

### Recommended Tools

- [Visual Studio Code](https://code.visualstudio.com/) with Markdown extensions
- [GitHub Desktop](https://desktop.github.com/) (optional, for those who prefer GUI)
- Modern web browser for testing documentation sites

### Troubleshooting Footer
## Troubleshooting Common Issues

### MkDocs Installation Problems

**Issue**: `command not found: mkdocs`  
**Solution**: Ensure Python and pip are properly installed, then run `pip install mkdocs`

**Issue**: Permission denied errors  
**Solution**: Use `pip install --user mkdocs` or consider using a virtual environment

### Build and Serve Issues

**Issue**: Port already in use  
**Solution**: Use a different port with `mkdocs serve -a localhost:8001`

**Issue**: Missing dependencies  
**Solution**: Install required packages: `pip install -r requirements.txt`

### GitHub Pages Deployment Issues

**Issue**: Site not updating after push  
**Solution**: Check GitHub Actions logs and ensure the workflow file is correctly configured

**Issue**: Custom domain not working  
**Solution**: Verify DNS settings and check the CNAME file in your repository

### Getting Help

- Check the [MkDocs documentation](https://www.mkdocs.org/)
- Review GitHub Issues in your repository
- Consult the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) documentation

### Workshop Information Footer  
---

## Workshop Information

**Workshop Duration**: 4-6 hours  
**Skill Level**: Beginner to Intermediate  
**Format**: Self-paced with hands-on exercises

### What You'll Learn

By completing this workshop, you'll master:

- Modern documentation tools and workflows
- Audience-centered content design
- Professional site deployment strategies
- AI-assisted content creation techniques

### Workshop Structure

This workshop follows a progressive learning path:

1. **Understand** your audience and their needs
2. **Design** effective content structure and flow  
3. **Implement** with modern tools like MkDocs
4. **Enhance** with advanced features and styling
5. **Accelerate** using AI-assisted workflows
6. **Deploy** professionally with automated pipelines

### Support and Feedback

- **Repository**: [Workshop Documentation Best Practices](https://github.com/microsoft/ai-tour-26-workshop-docs-architecture)
- **Issues**: Report problems or suggestions via GitHub Issues
- **Community**: Join discussions in the repository Discussions section

---

*This workshop is part of Microsoft's commitment to empowering developers with modern documentation practices.*

Step 4: Add Visual Enhancements and Media¶

Enhance your documentation with images, diagrams, and interactive media elements.

Add image examples with lightbox functionality:

Markdown
## Visual Content and Media

### Images with Lightbox
Click on any image to view it in full size with the lightbox feature:

![Workshop Planning Diagram](../media/workshop-planning.png "Click to enlarge")
*Workshop planning and structure overview*

![Audience Analysis Template](../media/audience-template.png "Click to enlarge") 
*Example of completed audience analysis template*

Create placeholder images (you can replace these later):

Bash
cd docs/docs/media/
# Create simple placeholder files or add your own images
echo "Placeholder workshop diagram" > workshop-planning.png
echo "Placeholder audience template" > audience-template.png

Add interactive content examples:

Markdown
### Code Annotations
You can add numbered annotations to code blocks:

```python
def setup_workshop_environment():
    """Set up the development environment for the workshop."""

    # Install required packages (1)
    install_dependencies()

    # Configure development settings (2)
    configure_environment()

    # Verify everything works (3)
    run_validation_tests()

    return "Environment ready!" # (4)

Install all packages listed in requirements.txt
Set up configuration files and environment variables
Run automated tests to ensure proper installation
Return confirmation message to indicate success ```

Step 5: Configure Advanced Markdown Extensions¶

Enhance your markdown processing with additional extensions for richer content.

Update your mkdocs.yml to include advanced extensions:

YAML
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - attr_list
  - md_in_html
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - footnotes
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.tilde

Add examples using these extensions:

Markdown
### Advanced Text Formatting

You can use various text formatting options:

- ==Highlighted text== for emphasis
- ^^Inserted text^^ for additions
- ~~Deleted text~~ for removals
- Text with H~2~O subscript
- Text with X^2^ superscript

### Keyboard Shortcuts
Use ++ctrl+alt+del++ to restart or ++cmd+space++ to search on Mac.

### Footnotes
This statement needs a reference[^1].

[^1]: This is the footnote content providing additional context.

### Critic Markup for Reviews
Don't {--delete this--} {++add this++} content when reviewing.

This is {~~wrong~>correct~~} information.

{==Highlight important==}{>>Add a comment here<<} sections.

Step 6: Test and Optimize Your Advanced Features¶

Verify that all advanced features work correctly and provide a good user experience.

Start your MkDocs server and test each feature:
Bash
1
mkdocs serve

Create a testing checklist:

Markdown
## Feature Testing Checklist

Test each advanced feature to ensure proper functionality:

- [ ] All admonition types render with correct styling
- [ ] Collapsible admonitions expand and collapse properly  
- [ ] Sticky tabs maintain selection across different pages
- [ ] Include content appears correctly in target pages
- [ ] Images display and lightbox functionality works
- [ ] Code annotations appear on hover or click
- [ ] Advanced text formatting renders correctly
- [ ] Footnotes link properly to their definitions

Verify responsive design:
- Test on mobile device or resize browser window
- Ensure tabs work properly on smaller screens
- Check that admonitions remain readable
- Confirm navigation remains functional

Exercise Results and Validation¶

After completing this lab, you should have:

✅ A comprehensive demo page showcasing all advanced features
✅ Multiple types of admonitions for different content needs
✅ Working sticky tabs that maintain user preferences
✅ Reusable content includes for common sections
✅ Enhanced visual content with lightbox functionality
✅ Advanced markdown formatting capabilities
✅ All features tested and working across devices

Lab 4 Complete!

You've mastered the advanced MkDocs features that will make your workshop documentation more engaging and professional. In Lab 5, we'll explore how AI tools can accelerate your content creation process.

Troubleshooting Advanced Features¶

Issue: "Admonitions don't have custom styling" Solution: Ensure the admonition extension is enabled in your mkdocs.yml and custom CSS is properly loaded.

Issue: "Sticky tabs not working across pages" Solution: Verify you're using the pymdownx.tabbed extension with alternate_style: true and that tab labels are consistent.

Issue: "Include content not appearing" Solution: Check the file path in your include statement and ensure the include-markdown plugin is installed and enabled.

Issue: "Code annotations not displaying" Solution: Verify that both pymdownx.highlight and pymdownx.superfences are configured with the correct options.

Best Practices for Advanced Features¶

Use admonitions sparingly - Too many callouts reduce their effectiveness
Keep tab labels consistent - This ensures the sticky functionality works properly
Organize includes logically - Group related reusable content together
Test on multiple devices - Ensure features work well on both desktop and mobile
Consider accessibility - Ensure color choices and interactions work for all users