PHP Markdown Rendering Library

Derafu Markdown is a PHP library that provides a powerful Markdown rendering engine with support for advanced extensions. It leverages league/commonmark and additional features to enhance Markdown processing for documentation, blogs, and dynamic content.

Features

• 📝 Full Markdown Support: Standard CommonMark and GitHub Flavored Markdown (GFM).
• 📚 Extended Capabilities: TOC, footnotes, mentions, permalinks, embeds, and more.
• 🎨 Custom Attributes: Add CSS classes and IDs to elements.
• 🔗 External Link Handling: Open in new tabs, add nofollow, etc.
• 🛠 Highly Configurable: Fine-tune Markdown behavior with options.
• 📦 Easy Integration: Works standalone or within any PHP project.
• 🏷 MIT Licensed: Open-source and free to use.

Installation

Install via Composer:

composer require derafu/markdown

Styles

The HTML of the Markdown is inside a <div class="markdown-body">, and the package has the CSS for it in resources/css:

@import '../../vendor/derafu/markdown/resources/css/markdown.css';

The files that markdown.css imports are resolved relative to its path, so the three have to stay in the same directory.

Usage

Basic Rendering

use Derafu\Markdown\Service\MarkdownCreator;
use Derafu\Markdown\Service\MarkdownService;

$markdownService = new MarkdownService(new MarkdownCreator());

echo $markdownService->render('example.md');

Rendering with Layout

$data = [
    '__view_layout' => '/absolute/path/to/layout.php',
    '__view_title' => 'My Markdown Page',
];

echo $markdownService->render('example.md', $data);

The data is passed by reference (the front matter of the template is merged into it), so it must be a variable. The layout must be an absolute path, receives the rendered HTML in $__content, and every other key of the data as a variable (a key never replaces the variables of the service itself).

Available Extensions

✅ GitHub Flavored Markdown (GFM)

• Task lists:

- [x] Completed
- [ ] Pending

• Tables:

| Name  | Age |
|-------|-----|
| John  | 25  |
| Alice | 30  |

📌 Table of Contents (TOC)

## Section 1
## Section 2

🔗 Header Permalinks

### Important Header

Generates an anchor link like #important-header.

📝 Footnotes

Here is a reference[^1].

[^1]: Footnote text.

🏷 Custom Attributes

### Title {.custom-class}

🔗 External Links Handling

[Google](https://www.google.com)

Adds attributes like rel="noopener noreferrer".

📌 Mentions & Issues

Hello @user, check issue #123.

Links to GitHub profiles and issues.

🎥 Embeds

https://www.youtube.com/watch?v=dQw4w9WgXcQ

Automatically embeds videos.

Advanced Configuration

You can customize the behavior of Markdown processing by passing an options array to MarkdownCreator:

$options = [
    'environment' => [
        'mentions' => [
            '@' => ['generator' => 'https://github.com/%s'],
            '#' => ['generator' => 'https://github.com/derafu/markdown/issues/%d']
        ]
    ]
];

$creator = new MarkdownCreator($options);

Template Metadata Support

Markdown templates can include metadata in YAML format:

---
__view_title: "Markdown Template Guide"
---