django-actual-admin-docs

Render Markdown documentation directly in the Django admin`.

• Support for nested subfolders
• Comprehensive Markdown format (link to which spec)
• Provides default styles for Markdown rendering

Installation

1. Install the django-actual-admin-docs package:

   • pip install django-actual-admin-docs[highlight] if you want to enable syntax highlighting in code blocks. This adds Pygments as a dependency.

   • pip install django-actual-admin-docs if you don't need that and want to keep your third party dependencies lean.

2. Add actual_admin_docs to your INSTALLED_APPS setting:

   INSTALLED_APPS = [
     "django.contrib.admin",
     "actual_admin_docs",
     ...
   ]
   

3. Add the documentation urlpattern, above your admin urls:

   from django.contrib import admin
   from django.urls import include, path
   
   urlpatterns = [
       path("admin/docs/", include("actual_admin_docs.urls")),
       path("admin/", admin.site.urls),
   ]
   

4. Add a DOCS_ROOT setting which should be a pathlib.Path pointing to the docs directory:

   DOCS_ROOT = BASE_DIR / "docs"
   

Documentation folder structure

You can use folders, subfolders, files in folders, etc.

🗂 docs/
│
├── 🗂 subfolder   
│   │   
│   ├── 🗂 subfolder with spaces
│   │   └── 📝 another-file.md
│   │ 
│   ├── 📝 another-file.md
│   └── 📝 index.md
│
├── 🗂 img    
│   └── 🌁 cat_studying_glasses.jpg
│
├── 📝 index.md
└── 📝 markdown-sample.md

Use regular Markdown links to link to other documents or objects:

A link to [another document](./markdown-sample.md) is just a regular Markdown link. Documents in subdirectories [are supported too](./subfolder/another-file.md).

For images, downloads etc. use regular markdown markup too:

![A cat judging your code](./img/cat_studying_glasses.jpg)
[Click to download](./img/./img/cat_studying_glasses.jpg)

Custom CSS

Overwrite the actual-admin-docs.css file to add your custom styles.

🤺 Local Development

$ poetry install
$ poetry run pytest
$ DJANGO_SETTINGS_MODULE=actual_admin_docs.tests.testproject.settings poetry run django-admin runserver

Changelog

v0.4 2024-11-06

• Sample documentation for testing purpose is now part of the module.
• Added testing with docs.

v0.3 2024-11-06

• Improved local test setup,
• Index files are consistently recognized in subfolders.
• Pygments as a dependency is now optional.

v0.2 2024-11-05

• Added syntax highlighting for fenced code blocks.
• Added Pygments as a dependency.

v0.1 2024-11-05

• Initial version.