Derafu: Markdown - PHP Markdown Rendering Library

GitHub last commit CI Workflow GitHub code size in bytes GitHub Issues Total Downloads Monthly Downloads

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

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. πŸš€