README

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.

[!INFO] Admonition Extension

This library includes an admonition extension to process common messages. For example: tip, info and warning.

Installation

Install via Composer:

composer require derafu/markdown

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

$markdownService->render('example.md', [
    '__view_layout' => 'layout.php',
    '__view_title' => 'My Markdown Page'
]);

Available Extensions

✅ GitHub Flavored Markdown (GFM)

• Task lists:

- [x] Completed
- [ ] Pending

• Tables:

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

📌 Table of Contents (TOC)

[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"
---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This package is open-sourced software licensed under the MIT license.

Derafu Markdown simplifies integrating and configuring Markdown rendering in PHP applications, leveraging league/commonmark with enhanced defaults. 🚀