README

GitDown

一个用于在 PHP 中解析（GitHub 风格）Markdown 的简单软件包。

警告

该软件包是一个欺诈。它所做的只是将您的 Markdown 发送到公共 GitHub API，该 API 返回解析结果。

了解这一点后，如果您不存储结果，或未利用提供的缓存功能，您的页面加载速度会变慢，或者更糟糕的是，可能会遇到 GitHub 的速率限制错误。

Markdown 解析非常麻烦，对我来说这种权衡是非常值得的，我希望您也能接受它。

安装

composer require calebporzio/gitdown

TLDR;

// Optionally set a GitHub Personal Access Token to increase rate-limit.
GitDown::setToken($token);

GitDown::parse($markdown);

// Uses Laravel's cache()->rememberForever() under the hood.
GitDown::parseAndCache($markdown);

可选地，将 @gitdown 片段添加到模板的 <head> 部分，并将 .markdown-body 类添加到包装元素中，以便为 GitHub markdown/code-syntax 调整样式。

<head>
    [...]
    @gitdown
</head>
<body>
    <div class="markdown-body">
        {!! GitDown::parseAndCache($content) !!}
    </div>
</body>

使用 GitHub 进行身份验证

未经身份验证，GitHub 会对您的 API 调用进行限制，每小时的调用次数为 60 次。如果您使用身份验证令牌，可以将此限制提高到每分钟 5000 次调用。强烈建议您使用“个人访问令牌”使用此软件包。要获取一个，请点击此处。（您可以为此令牌留空权限。）

首先，发布软件包的配置文件。

php artisan vendor:publish --provider="GitDown\GitDownServiceProvider"

然后，将以下条目添加到您的 .env 文件中。

[...]
GITHUB_TOKEN=your-token-here

用法

GitDown::parse($markdown);

// Will be cached forever. (suggested)
GitDown::parseAndCache($markdown);

// Will be cached for 24 hours. (minutes in Laravel < 5.8, seconds otherwise)
GitDown::parseAndCache($markdown, $seconds = 86400);

// Pass in your own custom caching strategy.
GitDown::parseAndCache($markdown, function ($parse) {
    return Cache::rememberForever(sha1($markdown), function () use ($parse) {
        return $parse();
    });
});

允许危险标记

默认情况下，GitHub 会清理它认为“不安全”的 HTML 标签，如 <iframe>。然而，使用 <iframe> 在 Markdown 中嵌入视频或音频很常见。

GitDown 可以通过在 config/gitdown.php 中的 allowedTags 配置数组选项中填充您想防止解析的标签来智能地保留您的标签。

"allowedTags" => [
    'iframe',
],

非 Laravel 使用

您可以通过将令牌传递给 GitDown 的构造函数来设置 GitHub 个人访问令牌。new GitDown\GitDown($token)

// You can pass config options into the constructur:
$gitDown = new GitDown\GitDown(
    $token = 'foo',
    $context = 'your/repo',
    $allowedTags = []
);

$gitDown->parse($markdown);

// Pass in your own custom caching strategy.
$gitDown->parseAndCache($markdown, function ($parse) {
    return Cache::rememberForever(sha1($markdown), function () use ($parse) {
        return $parse();
    });
});

Markdown/Syntax CSS

使用 CSS 调整 Markdown 一直让我感到很痛苦。更不用说尝试在代码块中调整语法样式了。不用担心！

GitDown 随带所有您需要的 CSS，以便使您的 Markdown 看起来与 GitHub 上的完全一样。只需在 HTML 页面的某个位置添加此代码即可，最好是在 <head> 部分靠近其他样式表的位置。

<head>
    [...]
    @gitdown
</head>

非 Laravel

<head>
    [...]
    <style><?php echo GitDown\GitDown::styles(); ?></style>
</head>

好了！这就是您需要的一切，让一切看起来都很好 🤙。

如果您不希望在页面上直接输出 CSS，您可以使用 NPM 将样式添加到您的样式表中。

使用npm安装primer-markdown和github-syntax-light --save

现在您可以将SCSS文件包含到您的Sass打包器中

@import "primer-markdown/index.scss";
// The relative directories may be a little different for you.
@import "./../../node_modules/github-syntax-light/lib/github-light.css";

GitHub Flavored Markdown

要为GitDown启用GFM解析，请将config/gitdown.php中的"context"条目设置为仓库名称。

"context" => "your/repo",

享受吧！

希望这能让您的生活更轻松。如果真的有帮助，请在微博上对项目表示喜爱，并@我：[calebporzio](https://twitter.com/calebporzio)

calebporzio / gitdown

维护者

详细信息