# 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
```bash
pip install mkdocs-freetext
```
### Basic Configuration
Add the plugin to your `mkdocs.yml`:
```yaml
plugins:
- freetext
```
### Simple Question Example
```markdown
!!! 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
```markdown
!!! 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](docs/configuration.md)** - All available options
- **[Question Syntax](docs/question-syntax.md)** - How to create questions
- **[Assessment Syntax](docs/assessment-syntax.md)** - How to create assessments
- **[Rich Content](docs/rich-content.md)** - Using diagrams, code, and images
- **[Theming](docs/theming.md)** - Customizing appearance
- **[Examples](docs/examples.md)** - 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
```markdown
!!! 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
```markdown
!!! 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](LICENSE) file for details.
## 🔗 Links
- [PyPI Package](https://pypi.org/project/mkdocs-freetext/)
- [GitHub Repository](https://github.com/D-Kearsey/mkdocs-freetext)
- [Documentation](https://d-kearsey.github.io/mkdocs-freetext/)
- [Issue Tracker](https://github.com/D-Kearsey/mkdocs-freetext/issues)
## 🏆 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
Raw data
{
"_id": null,
"home_page": "https://github.com/your-username/mkdocs-freetext",
"name": "mkdocs-freetext",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Drew Kearsey <drew.kearsey@kubrickgroup.com>",
"keywords": "mkdocs, plugin, freetext, questions, assessment, education, material, interactive, learning",
"author": "Your Name",
"author_email": "Drew Kearsey <drew.kearsey@kubrickgroup.com>",
"download_url": "https://files.pythonhosted.org/packages/7f/0b/170de465f21b4d539a3f0129b19565464a695b09e093288810a0807c009b/mkdocs_freetext-1.0.0.tar.gz",
"platform": null,
"description": "# MkDocs Free-Text Questions Plugin\n\nA comprehensive MkDocs plugin for adding interactive free-text input questions and assessments to your documentation. Perfect for educational content, tutorials, and training materials.\n\n## \u2728 Features\n\n- **Interactive Questions**: Add free-text input questions directly to your documentation\n- **Multi-Question Assessments**: Create comprehensive assessments with multiple questions\n- **Rich Content Support**: Questions support Mermaid diagrams, code blocks, images, and markdown\n- **Material Theme Integration**: Seamlessly integrates with MkDocs Material theme, including automatic dark/light mode support\n- **Persistent Storage**: Auto-saves user answers in browser localStorage\n- **Flexible Configuration**: Customize appearance, behavior, and validation\n- **Question Shuffling**: Optional randomization of assessment question order\n- **Character Counting**: Optional character counter for text inputs\n- **Sample Answers**: Show/hide sample answers for learning reinforcement\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install mkdocs-freetext\n```\n\n### Basic Configuration\n\nAdd the plugin to your `mkdocs.yml`:\n\n```yaml\nplugins:\n - freetext\n```\n\n### Simple Question Example\n\n```markdown\n!!! freetext\n question: What is the capital of France?\n placeholder: Enter your answer here...\n marks: 2\n show_answer: true\n answer: Paris is the capital of France.\n```\n\n### Assessment Example\n\n```markdown\n!!! freetext-assessment\n title: Python Basics Assessment\n shuffle: true\n \n question: What is a variable in Python?\n marks: 3\n placeholder: Describe what a variable is...\n \n ---\n \n question: Explain the difference between a list and a tuple.\n marks: 5\n placeholder: Compare lists and tuples...\n```\n\n## \ud83d\udcd6 Documentation\n\n- **[Configuration Reference](docs/configuration.md)** - All available options\n- **[Question Syntax](docs/question-syntax.md)** - How to create questions\n- **[Assessment Syntax](docs/assessment-syntax.md)** - How to create assessments\n- **[Rich Content](docs/rich-content.md)** - Using diagrams, code, and images\n- **[Theming](docs/theming.md)** - Customizing appearance\n- **[Examples](docs/examples.md)** - Real-world usage examples\n\n## \ud83c\udfa8 Material Theme Integration\n\nThis plugin is designed to work seamlessly with the Material for MkDocs theme:\n\n- Automatic light/dark mode support using Material CSS variables\n- Consistent styling with Material design principles\n- Responsive design that works on all devices\n- Admonition-based syntax that integrates naturally with Material\n\n## \ud83d\udd27 Configuration Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `question_class` | string | `freetext-question` | CSS class for question containers |\n| `assessment_class` | string | `freetext-assessment` | CSS class for assessment containers |\n| `enable_css` | boolean | `true` | Enable built-in CSS styling |\n| `shuffle_questions` | boolean | `false` | Shuffle question order in assessments |\n| `show_character_count` | boolean | `true` | Show character counter on text inputs |\n\n## \ud83c\udf1f Examples\n\n### Basic Question with Rich Content\n\n```markdown\n!!! freetext\n question: Analyze the following Python code and explain what it does:\n \n ```python\n def fibonacci(n):\n if n <= 1:\n return n\n return fibonacci(n-1) + fibonacci(n-2)\n ```\n \n What is the time complexity of this implementation?\n \n marks: 5\n placeholder: Explain the code and analyze its complexity...\n```\n\n### Assessment with Mermaid Diagram\n\n```markdown\n!!! freetext-assessment\n title: System Design Assessment\n \n question: Based on this system architecture, identify potential bottlenecks:\n \n ```mermaid\n graph TD\n A[User] --> B[Load Balancer]\n B --> C[Web Server 1]\n B --> D[Web Server 2]\n C --> E[Database]\n D --> E\n ```\n \n marks: 10\n placeholder: Identify and explain potential bottlenecks...\n```\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udd17 Links\n\n- [PyPI Package](https://pypi.org/project/mkdocs-freetext/)\n- [GitHub Repository](https://github.com/D-Kearsey/mkdocs-freetext)\n- [Documentation](https://d-kearsey.github.io/mkdocs-freetext/)\n- [Issue Tracker](https://github.com/D-Kearsey/mkdocs-freetext/issues)\n\n## \ud83c\udfc6 Why Choose MkDocs Free-Text?\n\n- **Educational Focus**: Built specifically for learning and assessment\n- **Modern Design**: Beautiful, responsive interface that works everywhere\n- **Rich Content**: Support for diagrams, code, images, and complex markdown\n- **Developer Friendly**: Clean API, extensive documentation, and active maintenance\n- **Production Ready**: Used in educational institutions and corporate training\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive MkDocs plugin for adding interactive free-text questions and assessments",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/yourusername/mkdocs-freetext/issues",
"Documentation": "https://github.com/yourusername/mkdocs-freetext",
"Homepage": "https://github.com/yourusername/mkdocs-freetext",
"Repository": "https://github.com/yourusername/mkdocs-freetext"
},
"split_keywords": [
"mkdocs",
" plugin",
" freetext",
" questions",
" assessment",
" education",
" material",
" interactive",
" learning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f5581491932098fff34235fddb47ad4f5126ea610ee2e8de89eaed9e3bac0214",
"md5": "12e918c6c0162a98f4d2510bf2842cb9",
"sha256": "75ea195143439f559f16dfcf3425801b46cfa40c67b946652f342bfdb46c50aa"
},
"downloads": -1,
"filename": "mkdocs_freetext-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "12e918c6c0162a98f4d2510bf2842cb9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 15810,
"upload_time": "2025-07-23T08:15:44",
"upload_time_iso_8601": "2025-07-23T08:15:44.243704Z",
"url": "https://files.pythonhosted.org/packages/f5/58/1491932098fff34235fddb47ad4f5126ea610ee2e8de89eaed9e3bac0214/mkdocs_freetext-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7f0b170de465f21b4d539a3f0129b19565464a695b09e093288810a0807c009b",
"md5": "93f21b7e07aa8e51a13df95fbda9c78e",
"sha256": "18fed66b2e0328f82397cc5409fb3033768df33b267e57f2bad519f1e56f5c08"
},
"downloads": -1,
"filename": "mkdocs_freetext-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "93f21b7e07aa8e51a13df95fbda9c78e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 17646,
"upload_time": "2025-07-23T08:15:45",
"upload_time_iso_8601": "2025-07-23T08:15:45.336359Z",
"url": "https://files.pythonhosted.org/packages/7f/0b/170de465f21b4d539a3f0129b19565464a695b09e093288810a0807c009b/mkdocs_freetext-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 08:15:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "your-username",
"github_project": "mkdocs-freetext",
"github_not_found": true,
"lcname": "mkdocs-freetext"
}
JSON
