README

简介

Markdom 是一个 Laravel 扩展包，使得将 markdown 转换为美观的 html 变得简单。它添加了类，并允许你自动进行代码高亮。

安装

使用 composer 安装包

$ composer require sinnbeck/markdom

之后，将 facade 添加到你的 config/app.php 别名数组中是个好主意。

'Markdom' => Sinnbeck\Markdom\Facades\Markdom::class,

发布配置

要发布配置文件，只需运行以下命令即可将 markdom.php 添加到你的配置目录。

php artisan vendor:publish --tag=markdom-config

用法

Markdom 附带了一个 blade 辅助函数，可以轻松地将 markdown 转换为 html

@markdom($markdown)

你也可以通过 facade 来调用它

Markdom::toHtml($markdown)

配置

Markdom 的主要功能是为你的渲染 html 添加类。这要求你在 markdom.php 中设置一个类映射。这决定了哪些元素将获得哪些类。这里有一个使用 TailwindCss 语法快速示例。

    'classes' => [
        'h1'     => 'text-3xl font-bold mt-1 mb-2 border-b',
        'h2'     => 'text-2xl font-bold my-1 border-b',
        'h3'     => 'text-xl font-bold my-1',
        'p'      => 'py-2',
        'ul'     => 'list-disc list-inside',
        'ul ul'  => 'pl-8 list-disc list-inside',
        'ol'     => 'list-decimal list-inside',
        'pre'    => 'my-1'
    ],

键可以是任何 CSS 选择器，这意味着你也可以做 ul > li > ul 或者甚至是 .classname。类是按照它们在配置中列出的顺序解析的，这意味着你可以向之前设置的类添加额外的类。

    'classes' => [
        'h1'     => 'title text-3xl ',
        'h2'     => 'title text-2xl',
        'h3'     => 'title text-xl',
        '.title' => 'font-bold border-b',
    ],

上面的示例将为标题元素添加类 title，然后为每个元素添加 'font-bold border-b'。
结果

<h1 class="title text-3xl font-bold border-b">Title</h1>
<h2 class="title text-2xl font-bold border-b">Subtitle</h2>
<h3 class="title text-xl font-bold border-b">More</h3>

添加 id 和 href

Markdom 使得为标题添加 id 和链接（<a href />）变得简单。只需在 markdom.php 配置文件中将 links.enabled 设置为 true，Markdom 就会处理其余部分。

检查文档以获取配置选项。

Markdown 配置

可以调整 markdown 的解析。底层，Mardom 使用 league/commonmark，这意味着所有在 commonmark 键下的设置都是直接发送到 CommonMark。有关可用设置的列表，请参阅此处：[https://commonmark.thephpleague.com/2.3/configuration/#configuration](https://commonmark.thephpleague.com/2.3/configuration/#configuration)

Markdown 扩展

CommonMark 附带了许多扩展。可以将它们添加到 commonmark_extensions 数组中，以便自动加载。有关可用扩展的列表，请参阅此处：[https://commonmark.thephpleague.com/2.3/extensions/overview/](https://commonmark.thephpleague.com/2.3/extensions/overview/)

代码高亮

如果你使用 markdown 解析代码，可以通过在 .env 文件中设置 MARKDOM_CODE_HIGHLIGHT=true 来启用代码高亮器。这将自动将 highlight.js 类添加到代码标签中找到的代码。

CommonMark 将 `somecode` 和
```
somecode
```
转换为 <code>somecode</code> 和 <pre><code>somecode</code></pre>，这将传递给 scrivo/highlight.php（highlight.js 的 PHP 实现）。

高亮主题和 CSS

可以自动设置代码样式。这可以通过将 @markdomStyles() 指令添加到你的页面来完成。这将嵌入 highlight.js CSS 到你的页面中。你可以传递主题名称到方法中，以获取特定的样式表 @markdomStyles('purebasic')

高亮主题

Highlight.js 目前支持91种主题。您可以通过使用 Markdom::getAvailableThemes() 获取这些主题的数组。如果允许用户选择主题，这可以用于渲染下拉菜单。

<select>
    @foreach(Markdom::getAvailableThemes() as $style)
        <option value="{{$style}}">{{$style}}</option>
    @endforeach
</select> 

示例

控制器（Markdown 文件也可以从数据库或文件中加载）

    public function index()
    {
        $markdown = 
<<<markdown
# Title
## Subtitle

* List item
* List item 2
1. Numbered list item
2. Numbered list item 2

### Code

\```
$this->foo = 'bar';
\```

Inline code `const $x = [1, 2, 3];`

### Text formatting
**Bold** \
__Bold__ \
_Italic_ \
~~Crossed~~

### Escaped html
<script>alert()</script>
markdown;

        return view('markdown.index', compact('markdown'));
    }

index.blade.php

@extends('layouts.app')
@section('content')
    @markdom($markdown)
@endsection

Livewire

Markdom 与 Livewire 配合得很好，且无需任何 JavaScript。

您可以在以下链接中找到一个使用 Livewire 的自动更新 Markdown 编辑器的示例： https://github.com/sinnbeck/markdom-livewire

更新通知！

如果您是从版本 1.x 升级到 2.x，请注意，由于 CommonMark 的变化，配置格式已经发生了很大变化！因此，检查 /config 目录中的新示例配置文件是个好主意。

测试

使用以下命令运行测试

vendor/bin/pest

待办事项

• 处理使用 <link 语法加载 highlight 样式
• highlight 样式的压缩
• 使用 highlight 样式的 cdn 版本的指南（内联代码会中断！）
• 研究手动将语言传递给 highlight.php

致谢

• Markdown 解析： CommonMark
• DOM 操作： HtmlPageDom
• 代码高亮： highlight.php