PHPackages                             phpsoftbox/markdown - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. phpsoftbox/markdown

ActiveLibrary[Utility & Helpers](/categories/utility)

phpsoftbox/markdown
===================

Safe Markdown renderer for PhpSoftBox documentation

01↑2900%PHP

Since Jun 26Pushed todayCompare

[ Source](https://github.com/phpsoftbox/markdown)[ Packagist](https://packagist.org/packages/phpsoftbox/markdown)[ RSS](/packages/phpsoftbox-markdown/feed)WikiDiscussions master Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

PhpSoftBox Markdown
===================

[](#phpsoftbox-markdown)

Компонент безопасного рендера Markdown-документов.

Пакет дает framework-level API поверх Markdown parser и YAML parser. Он умеет разбирать Markdown source, front matter, строить HTML, TOC, heading anchors, обрабатывать расширения синтаксиса и возвращать diagnostics без привязки к тому, где именно используется результат: в документации, админке, CMS, письмах или другом app-layer.

```
use PhpSoftBox\Markdown\MarkdownRenderer;

$document = new MarkdownRenderer()->render(frontMatter(); // ['title' => 'Установка', ...]
```

Если YAML невалидный, компонент вернет diagnostic `front_matter.invalid`, но тело документа останется доступным.

TOC И Anchors
-------------

[](#toc-и-anchors)

Заголовки получают стабильные `id`:

```
## Install
## Install
```

Результат:

```
Install
Install
```

Диапазон TOC настраивается:

```
use PhpSoftBox\Markdown\MarkdownRenderOptions;

$document = $renderer->render($source, new MarkdownRenderOptions(
    tocMinHeadingLevel: 2,
    tocMaxHeadingLevel: 3,
));
```

Links И Assets
--------------

[](#links-и-assets)

Renderer не знает файловую структуру, правила роутинга и публичные URL приложения. Для этого передается resolver:

```
use PhpSoftBox\Markdown\Contracts\MarkdownLinkResolverInterface;
use PhpSoftBox\Markdown\MarkdownRenderContext;
use PhpSoftBox\Markdown\MarkdownResolvedAsset;
use PhpSoftBox\Markdown\MarkdownResolvedLink;

final class AppMarkdownLinkResolver implements MarkdownLinkResolverInterface
{
    public function resolveLink(string $target, MarkdownRenderContext $context): MarkdownResolvedLink
    {
        return MarkdownResolvedLink::resolved('/content/' . trim($target, './'));
    }

    public function resolveAsset(string $target, MarkdownRenderContext $context): MarkdownResolvedAsset
    {
        return MarkdownResolvedAsset::resolved('/assets/content/' . trim($target, './'));
    }
}
```

```
$document = $renderer->render($source, new MarkdownRenderOptions(
    basePath: '/content',
    currentDocumentPath: 'articles/install.md',
    linkResolver: new AppMarkdownLinkResolver(),
));
```

Если resolver не смог найти цель, он возвращает `MarkdownResolvedLink::unresolved()`или `MarkdownResolvedAsset::unresolved()`. Renderer добавит diagnostics `link.unresolved` или `asset.unresolved`.

Code Blocks
-----------

[](#code-blocks)

Поддерживается `title` в info string:

```
```php title="src/Action.php"
echo 'ok';
```
```

В HTML появятся `data-language`, `data-title` и подпись блока.

Если задан `allowedCodeLanguages`, неизвестный язык попадет в diagnostic `code.language_unknown`.

Admonitions
-----------

[](#admonitions)

```
:::warning
Перед деплоем проверьте переменные окружения.
:::
```

Поддержанные типы:

- `note`;
- `tip`;
- `info`;
- `warning`;
- `danger`.

Неизвестный тип возвращает diagnostic `admonition.unknown`.

Tabs
----

[](#tabs)

Tabs-блок задается контейнером `:::tabs` и секциями `@tab`:

```
:::tabs
@tab PHP
```php
echo 'ok';
```

@tab JavaScript
```js
console.log('ok');
```
:::
```

Renderer вернет статичный HTML:

```

    ...
    ...

```

Компонент не навязывает JS-поведение. Приложение может подключить собственный скрипт/React-компонент поверх классов `markdown-tabs*` и `data-tab`.

Некорректный блок возвращает diagnostic `tabs.invalid`.

MDX-Lite Components
-------------------

[](#mdx-lite-components)

Компонент не выполняет JSX и не компилирует настоящий MDX. Backend-часть поддерживает безопасные component islands: renderer распознает whitelisted компоненты, валидирует props через resolver и возвращает HTML-placeholder для будущего фронтового registry/hydration.

Поддержанный синтаксис:

```

**Важно:** проверьте настройки.

```

Поддержанные props:

- строки: `type="warning"` или `type='warning'`;
- boolean shorthand: `enabled`;
- простые литералы: `{true}`, `{false}`, `{null}`, `{3}`, `{3.14}`.

Произвольные JS expressions не выполняются и возвращают diagnostic `mdx.props_invalid`.

Resolver задает список разрешенных компонентов и может нормализовать props:

```
use PhpSoftBox\Markdown\Contracts\MarkdownComponentResolverInterface;
use PhpSoftBox\Markdown\MarkdownRenderContext;
use PhpSoftBox\Markdown\MarkdownResolvedComponent;

final class AppMarkdownComponentResolver implements MarkdownComponentResolverInterface
{
    public function resolveComponent(
        string $name,
        array $props,
        string $content,
        MarkdownRenderContext $context,
    ): MarkdownResolvedComponent {
        return match ($name) {
            'Alert' => MarkdownResolvedComponent::resolved('Alert', $props),
            'Icon'  => MarkdownResolvedComponent::resolved('Icon', $props),
            default => MarkdownResolvedComponent::unresolved($name),
        };
    }
}
```

```
$document = $renderer->render($source, new MarkdownRenderOptions(
    componentResolver: new AppMarkdownComponentResolver(),
));

$document->components();
```

HTML-placeholder выглядит так:

```

    Важно: проверьте настройки.

```

React/Vue/другой frontend-layer может позже подключить свой registry компонентов поверх `data-mdx-component` и `data-mdx-props`. Backend при этом уже отдает fallback HTML, metadata и diagnostics.

Ограничения backend MVP:

- только block-level компоненты;
- без `import/export`;
- без JSX expressions;
- без inline components внутри строки;
- без выполнения JavaScript.

HTML Safety
-----------

[](#html-safety)

По умолчанию raw HTML экранируется:

```
use PhpSoftBox\Markdown\MarkdownHtmlPolicy;
use PhpSoftBox\Markdown\MarkdownRenderOptions;

$document = $renderer->render($source, new MarkdownRenderOptions(
    htmlPolicy: MarkdownHtmlPolicy::Escape,
));
```

Доступные политики:

- `MarkdownHtmlPolicy::Escape`;
- `MarkdownHtmlPolicy::Strip`;
- `MarkdownHtmlPolicy::Allow`.

Даже при разрешенном HTML renderer блокирует опасные URL schemes: `javascript:`, `vbscript:`, `data:`.

Для внешних ссылок можно включить target/rel:

```
$document = $renderer->render($source, new MarkdownRenderOptions(
    externalLinkTarget: '_blank',
    externalLinksNoFollow: true,
));
```

Diagnostics
-----------

[](#diagnostics)

Минимальные коды:

- `front_matter.invalid`;
- `link.unresolved`;
- `asset.unresolved`;
- `html.disallowed`;
- `admonition.unknown`;
- `tabs.invalid`;
- `mdx.component_unknown`;
- `mdx.syntax_invalid`;
- `mdx.props_invalid`;
- `heading.duplicate_id`;
- `code.language_unknown`.

```
foreach ($document->diagnostics() as $diagnostic) {
    echo $diagnostic->code() . ': ' . $diagnostic->message();
}
```

Лицензия
--------

[](#лицензия)

MIT

###  Health Score

21

—

LowBetter than 18% of packages

Maintenance65

Regular maintenance activity

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/0279d150240c97d210034878b0467462246dc14d29b5618157ff6a8be49a50e3?d=identicon)[inspector-who](/maintainers/inspector-who)

---

Top Contributors

[![inspector-who](https://avatars.githubusercontent.com/u/6973963?v=4)](https://github.com/inspector-who "inspector-who (1 commits)")

### Embed Badge

![Health badge](/badges/phpsoftbox-markdown/health.svg)

```
[![Health](https://phpackages.com/badges/phpsoftbox-markdown/health.svg)](https://phpackages.com/packages/phpsoftbox-markdown)
```

###  Alternatives

[miladrahimi/php-enum

A PHP Abstract Enum Class

1113.5k](/packages/miladrahimi-php-enum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)