{"id":18026539,"url":"https://github.com/omenapps/django-help","last_synced_at":"2026-03-17T03:34:40.411Z","repository":{"id":257826307,"uuid":"866874303","full_name":"OmenApps/django-help","owner":"OmenApps","description":"A Multilingual Knowledge Base application for Django","archived":false,"fork":false,"pushed_at":"2024-12-16T09:48:35.000Z","size":191,"stargazers_count":2,"open_issues_count":14,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-12T09:39:52.795Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OmenApps.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-03T03:14:38.000Z","updated_at":"2024-11-01T00:37:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"34e71b90-421d-41fd-8fae-a11987c35a49","html_url":"https://github.com/OmenApps/django-help","commit_stats":null,"previous_names":["omenapps/django-help"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/OmenApps/django-help","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmenApps%2Fdjango-help","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmenApps%2Fdjango-help/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmenApps%2Fdjango-help/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmenApps%2Fdjango-help/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OmenApps","download_url":"https://codeload.github.com/OmenApps/django-help/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmenApps%2Fdjango-help/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270933731,"owners_count":24670489,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-30T08:07:16.683Z","updated_at":"2026-03-17T03:34:35.379Z","avatar_url":"https://github.com/OmenApps.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# django-help\n\n[![PyPI](https://img.shields.io/pypi/v/django-help.svg)][pypi status]\n[![Status](https://img.shields.io/pypi/status/django-help.svg)][pypi status]\n[![Python Version](https://img.shields.io/pypi/pyversions/django-help)][pypi status]\n[![License](https://img.shields.io/pypi/l/django-help)][license]\n\n[![Read the documentation at https://django-help.readthedocs.io/](https://img.shields.io/readthedocs/django-help/latest.svg?label=Read%20the%20Docs)][read the docs]\n[![Tests](https://github.com/OmenApps/django-help/actions/workflows/tests.yml/badge.svg)][tests]\n[![Codecov](https://codecov.io/gh/jacklinke/django-help/branch/main/graph/badge.svg)][codecov]\n\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white)][pre-commit]\n[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)][black]\n\n[pypi status]: https://pypi.org/project/django-help/\n[read the docs]: https://django-help.readthedocs.io/\n[tests]: https://github.com/OmenApps/django-help/actions?workflow=Tests\n[codecov]: https://app.codecov.io/gh/jacklinke/django-help\n[pre-commit]: https://github.com/pre-commit/pre-commit\n[black]: https://github.com/psf/black\n\n## Overview\n\n\u003e [!WARNING]\n\u003e This project is under active development and not yet ready for production use.\n\ndjango-help is a powerful and flexible Django package that provides a multilingual knowledge base and help system for Django applications. Its standout features include multi-language support and seamless import/export functionality, making it an ideal solution for creating and managing help content across different languages and projects.\n\n## Key Features\n\n1. **Multi-Language Support**:\n   - Create and manage help content in multiple languages\n   - Easily translate articles, categories, and tags\n   - Language-specific content display based on user preferences or settings\n\n2. **Import/Export Functionality**:\n   - Import single articles or bulk import multiple articles\n   - Export individual articles or entire knowledge bases\n   - Support for Markdown format with YAML frontmatter for metadata\n\n3. **Article Management**:\n   - Create and edit help articles using Markdown for rich text formatting\n   - Organize content with categories and tags\n   - Set article visibility and highlight important content\n\n4. **Contextual Help**:\n   - Associate articles with specific URL paths for context-sensitive help\n   - Display relevant content based on the user's current location in the application\n\n5. **Search Functionality**:\n   - Full-text search across all articles, titles, and tags in multiple languages\n   - Customizable search results ranking and filtering\n\n6. **User Interface**:\n   - Responsive design for optimal viewing on various devices\n   - Customizable templates for seamless integration with your application's look and feel\n   - Modal view support for displaying help content without page navigation\n\n7. **Admin Interface**:\n   - User-friendly Django admin integration for content management\n   - Bulk actions for efficient article and category management\n\n8. **Extensibility**:\n   - Customizable base models and querysets for tailored functionality\n   - Hooks for adding custom authorization logic\n\n## Requirements\n\n- Python 3.10 or higher\n- Django 4.2 or higher\n- Additional dependencies:\n  - django-markdownx 4.0+: For Markdown editing and rendering\n  - django-translated-fields 0.13+: For multi-language support\n  - django-taggit 6.1+: For tagging functionality\n  - python-frontmatter 1.1+: For parsing Markdown files with metadata\n  - django-crispy-forms 2.3+: For enhanced form rendering\n  - crispy-bootstrap5 2024.2+: For Bootstrap 5 styling in crispy forms\n\n## Installation\n\nInstall django-help using pip:\n\n```console\n$ pip install django-help\n```\n\n## Quick Start Guide\n\n1. Add required apps to your `INSTALLED_APPS`:\n\n```python\nINSTALLED_APPS = [\n    ...\n    'django_help',\n    'markdownx',\n    'taggit',\n    'crispy_forms',\n    'crispy_bootstrap5',\n]\n```\n\nAnd add the django_help_tags to your `TEMPLATES` builtins:\n\n```python\nTEMPLATES = [\n    {\n        ...\n        'OPTIONS': {\n            'builtins': [\n                'django_help.templatetags.django_help_tags',\n            ],\n        },\n    },\n]\n```\n\n2. Include django-help URLs in your project's `urls.py`:\n\n```python\nfrom django.urls import include, path\n\nurlpatterns = [\n    ...\n    path('help/', include('django_help.urls')),\n]\n```\n\n3. Run migrations to create necessary database tables:\n\n```console\n$ python manage.py migrate django_help\n```\n\n4. Configure your static files settings to include django-help static files:\n\n```python\nSTATIC_URL = '/static/'\nSTATICFILES_DIRS = [\n    ...\n    ('django_help', 'path/to/your/django_help/static'),\n]\n```\n\n5. Start creating help content through the Django admin interface.\n\n## Multi-Language Support\n\ndjango-help uses django-translated-fields to provide robust multi-language support for your help content.\n\n### Configuration\n\n1. Define your project's languages in your project's settings, per Django's [translations documentation]:\n\n```python\nLANGUAGE_CODE = 'en'\nLANGUAGES = [\n    ('en', 'English'),\n    ('es', 'Spanish'),\n    ('fr', 'French'),\n    # Add languages as needed\n]\n```\n\n2. Configure additional language settings in `DJANGO_HELP_CONFIG`:\n\nThis configuration allows you to specify which languages are available for translation in django-help. To make translations for each language required or optional in models and forms, set the `blank` key for each language:\n\n```python\nDJANGO_HELP_CONFIG = {\n    \"EXTRA_LANGUAGES\": {\n        \"es\": {\"blank\": False},  # Spanish translations are required\n        \"fr\": {\"blank\": True},   # French translations are optional\n    },\n    # Other settings...\n}\n```\n\n### Creating Multi-Language Content\n\nWhen creating or editing articles in the admin interface, you'll see separate fields for each configured language:\n\n- Title (English)\n- Title (Spanish)\n- Title (French)\n- Content (English)\n- Content (Spanish)\n- Content (French)\n\nFill in the content for each language as needed. If a language is set to `\"blank\": True` in the configuration, it's optional.\n\n### Displaying Multi-Language Content\n\ndjango-help automatically displays content in the user's preferred language based on Django's language settings. You can also manually control the displayed language:\n\n```python\nfrom django.utils.translation import activate\n\nactivate('es')  # Switch to Spanish\n# Your view logic here\n```\n\n### Display help content in your templates:\n\n```html\n{% load django_help_tags %}\n\n\u003c!-- Display help button for the current path --\u003e\n{% django_help_current_path %}\n\n\u003c!-- Display help button for a specific category --\u003e\n{% django_help_category \"getting-started\" %}\n\n\u003c!-- Display help button for a specific article slug --\u003e\n{% django_help_slug \"how-to-reset-password\" %}\n\n\u003c!-- Display help button for a specific tag --\u003e\n{% django_help_tag \"account-management\" %}\n```\n\n## Import/Export Functionality\n\ndjango-help provides powerful import and export capabilities for managing your help content.\n\n### Exporting Articles\n\n1. In the Django admin interface, go to the DjangoHelp Articles section.\n2. Select the articles you want to export.\n3. Choose the \"Export selected articles to Markdown (.md) and/or ZIP\" action.\n4. If exporting a single article, you'll get a .md file. For multiple articles, you'll receive a ZIP archive.\n\n### Importing Articles\n\nYou can import articles individually or in bulk:\n\n1. Prepare your Markdown files with YAML frontmatter for metadata:\n\n```markdown\n---\ntitle: How to Reset Your Password\nslug: reset-password\ncategory: Account Management\ntags: password, account, security\n---\n\n# How to Reset Your Password\n\n1. Go to the login page\n2. Click on \"Forgot Password\"\n3. ...\n```\n\n2. In the Django admin interface, go to the DjangoHelp Articles section.\n3. Click on the \"Upload\" button.\n4. Choose either a single .md file or a ZIP archive containing multiple .md files.\n5. Submit the form to import the articles.\n\n### Bulk Import/Export\n\n__(This feature is planned for a future release.)__\n\nFor large-scale import or export operations, you can use management commands:\n\n```console\n# Export all articles\n$ python manage.py export_help_articles\n\n# Import articles from a directory\n$ python manage.py import_help_articles /path/to/article/directory\n```\n\n### Multi-Language Import/Export\n\nWhen exporting, each article's file will contain content for all configured languages:\n\n```markdown\n---\ntitle_en: How to Reset Your Password\ntitle_es: Cómo Restablecer tu Contraseña\ntitle_fr: Comment Réinitialiser Votre Mot de Passe\nslug: reset-password\ncategory: Account Management\ntags: password, account, security\n---\n\n# English Content\n\nHow to reset your password...\n\n# Contenido en Español\n\nCómo restablecer tu contraseña...\n\n# Contenu en Français\n\nComment réinitialiser votre mot de passe...\n```\n\nWhen importing, the system will automatically detect and populate the appropriate language fields based on the frontmatter and content structure.\n\n## Advanced Usage\n\n### Customizing Templates\n\nOverride default templates by creating your own in your project's template directory:\n\n- `django_help/pages-index.html`: Main help page\n- `django_help/pages-category.html`: Category listing page\n- `django_help/fragments/modal_content.html`: Article display modal\n- `django_help/markdownx/widget.html`: Markdown editor widget\n\n### Extending Models\n\nExtend base models for custom functionality:\n\n```python\nfrom django.db import models\n\nclass CustomHelpArticle(models.Model):\n    custom_field = models.CharField(max_length=100)\n\n    class Meta:\n        abstract = True\n\n    def custom_method(self):\n        # Custom functionality\n        pass\n```\n\nUpdate your `DJANGO_HELP_CONFIG` to use the custom model:\n\n```python\nDJANGO_HELP_CONFIG = {\n    \"BASE_MODEL\": \"myapp.models.CustomHelpArticle\",\n    # Other settings...\n}\n```\n\n## Contributing\n\nWe welcome contributions to django-help! Please see our [Contributor Guide] for details on how to get started, our code of conduct, and the process for submitting pull requests.\n\n## License\n\ndjango-help is distributed under the terms of the [MIT license][license]. This project is free and open-source software.\n\n## Support and Issues\n\nIf you encounter any problems or have questions, please [file an issue] on our GitHub repository. For general discussions or questions, you can use the Discussions tab on GitHub.\n\n## Credits\n\nThis project was generated from [@OmenApps]'s [Cookiecutter Django Package] template.\n\n[@omenapps]: https://github.com/OmenApps\n[pypi]: https://pypi.org/\n[cookiecutter django package]: https://github.com/OmenApps/cookiecutter-django-package\n[file an issue]: https://github.com/OmenApps/django-help/issues\n[pip]: https://pip.pypa.io/\n[license]: https://github.com/OmenApps/django-help/blob/main/LICENSE\n[contributor guide]: https://github.com/OmenApps/django-help/blob/main/CONTRIBUTING.md\n[command-line reference]: https://django-help.readthedocs.io/en/latest/usage.html\n[translations documentation]: https://docs.djangoproject.com/en/stable/topics/i18n/translation/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomenapps%2Fdjango-help","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomenapps%2Fdjango-help","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomenapps%2Fdjango-help/lists"}