mkdocs-freetext 1.0.0

A comprehensive MkDocs plugin for adding interactive free-text questions and assessments

MkDocs Free-Text Questions Plugin

A comprehensive MkDocs plugin for adding interactive free-text input questions and assessments to your documentation. Perfect for educational content, tutorials, and training materials.

✨ Features

• Interactive Questions: Add free-text input questions directly to your documentation
• Multi-Question Assessments: Create comprehensive assessments with multiple questions
• Rich Content Support: Questions support Mermaid diagrams, code blocks, images, and markdown
• Material Theme Integration: Seamlessly integrates with MkDocs Material theme, including automatic dark/light mode support
• Persistent Storage: Auto-saves user answers in browser localStorage
• Flexible Configuration: Customize appearance, behavior, and validation
• Question Shuffling: Optional randomization of assessment question order
• Character Counting: Optional character counter for text inputs
• Sample Answers: Show/hide sample answers for learning reinforcement

🚀 Quick Start

Installation

pip install mkdocs-freetext

Basic Configuration

Add the plugin to your mkdocs.yml:

plugins:
  - freetext

Simple Question Example

!!! freetext
    question: What is the capital of France?
    placeholder: Enter your answer here...
    marks: 2
    show_answer: true
    answer: Paris is the capital of France.

Assessment Example

!!! freetext-assessment
    title: Python Basics Assessment
    shuffle: true
    
    question: What is a variable in Python?
    marks: 3
    placeholder: Describe what a variable is...
    
    ---
    
    question: Explain the difference between a list and a tuple.
    marks: 5
    placeholder: Compare lists and tuples...

📖 Documentation

• Configuration Reference - All available options
• Question Syntax - How to create questions
• Assessment Syntax - How to create assessments
• Rich Content - Using diagrams, code, and images
• Theming - Customizing appearance
• Examples - Real-world usage examples

🎨 Material Theme Integration

This plugin is designed to work seamlessly with the Material for MkDocs theme:

• Automatic light/dark mode support using Material CSS variables
• Consistent styling with Material design principles
• Responsive design that works on all devices
• Admonition-based syntax that integrates naturally with Material

🔧 Configuration Options

Option	Type	Default	Description
question_class	string	freetext-question	CSS class for question containers
assessment_class	string	freetext-assessment	CSS class for assessment containers
enable_css	boolean	true	Enable built-in CSS styling
shuffle_questions	boolean	false	Shuffle question order in assessments
show_character_count	boolean	true	Show character counter on text inputs

🌟 Examples

Basic Question with Rich Content

!!! freetext
    question: Analyze the following Python code and explain what it does:
    
    ```python
    def fibonacci(n):
        if n <= 1:
            return n
        return fibonacci(n-1) + fibonacci(n-2)
    ```
    
    What is the time complexity of this implementation?
    
    marks: 5
    placeholder: Explain the code and analyze its complexity...

Assessment with Mermaid Diagram

!!! freetext-assessment
    title: System Design Assessment
    
    question: Based on this system architecture, identify potential bottlenecks:
    
    ```mermaid
    graph TD
        A[User] --> B[Load Balancer]
        B --> C[Web Server 1]
        B --> D[Web Server 2]
        C --> E[Database]
        D --> E
    ```
    
    marks: 10
    placeholder: Identify and explain potential bottlenecks...

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• PyPI Package
• GitHub Repository
• Documentation
• Issue Tracker

🏆 Why Choose MkDocs Free-Text?

• Educational Focus: Built specifically for learning and assessment
• Modern Design: Beautiful, responsive interface that works everywhere
• Rich Content: Support for diagrams, code, images, and complex markdown
• Developer Friendly: Clean API, extensive documentation, and active maintenance
• Production Ready: Used in educational institutions and corporate training