markdown_docs

Markdown Docs lets you publish a folder of Markdown files as browsable documentation pages inside the Drupal administration interface.

It is a lightweight solution for teams that already maintain internal guides, editor manuals, onboarding notes, or technical documentation in Markdown and want to make that content available directly in Drupal.

Features

• Renders Markdown files as admin documentation pages
• Adds a documentation landing page at /admin/documentation
• Builds navigation automatically from your documentation folder structure
• Uses the first H1 in each file as the page title
• Rewrites relative .md links to internal Drupal documentation routes
• Rewrites relative image paths to a secure image route
• Provides Ajax-powered search across documentation files
• Generates a table of contents from page headings
• Includes support for styled warning and tip callouts
• Falls back to an auto-generated overview page when no index.md exists
• Renders Mermaid diagrams from fenced code blocks (```mermaid)
• Editorial mode for creating, editing, and managing documentation pages directly in Drupal

Mermaid diagrams

Fenced code blocks with the mermaid language tag are automatically rendered as diagrams (flowcharts, sequence diagrams, etc.) using Mermaid.js. The library can be installed locally via npm or loaded automatically from a CDN as a fallback.

Editorial mode

When enabled, editorial mode adds an administration interface for managing documentation directly in Drupal:

• Create, edit, and delete documentation pages through a web form
• Rename and delete sections (folders)
• Upload and manage assets (images and other files)
• Controlled by a separate administer markdown_docs permission

This is useful for teams that want non-technical editors to maintain documentation without needing access to the filesystem or a code repository.

Typical use cases

• Editorial manuals
• Content governance documentation
• Internal support documentation
• Administrator handover notes
• Project-specific implementation guides

Requirements

• Drupal 10 or 11
• league/commonmark

Configuration

The module reads Markdown files from a configurable documentation directory. By default it looks for:

documentation/

You can change this through the module configuration:

docs_path: documentation

Expected structure

Example:

documentation/
  index.md
  editors/
    getting-started.md
    publishing.md
  admins/
    users.md

• index.md becomes the landing page
• each subdirectory becomes a navigation section
• each Markdown file becomes a documentation page

Permissions

The module provides two permissions:

• access markdown_docs — view documentation pages
• administer markdown_docs — create, edit, and delete documentation pages and sections (editorial mode)

Why use this module?

Many teams already write documentation in Markdown because it is portable, versionable, and easy to maintain in Git. Markdown Docs brings that content into Drupal without requiring a custom content model, extra editorial workflows, or manual page creation.

If your project documentation lives in the repository, this module makes it accessible to administrators and editors where they actually need it: inside Drupal.

🤖 Assisted Development

This module is maintained with the help of AI assistants for code generation, review, testing, and documentation. All code is carefully reviewed by the maintainers to ensure that quality and security standards are met.