包简介

A simple package to parse Github Flavored Markdown in PHP

README 文档

README

GitDown

A simple package for parsing (GitHub Flavored) Markdown in PHP.

WARNING

This package is a fraud. All it does is fire off your markdown to a public GitHub API that returns the parsed result.

Knowing this, if you don't store the result, or take advantage of the provided caching features, you'll end up with slow page loads, or worse, rate-limit errors from GitHub.

Markdown parsing is super annoying, and this tradeoff is well worth it to me, I hope you embrace it as well.

Installation

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);

Optionally, add the @gitdown snippet to your template's <head> section, and a .markdown-body class to a wrapper element, for GitHub markdown/code-syntax styling.

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

Authenticating With GitHub

Without authentication, GitHub will limit your API calls to 60 calls/hour. If you use authentication tokens, you can increase this limit to 5000 calls/minute. It is highly recommended that you use a "Personal Access Token" with this package. To obtain one, click here. (You can leave the permissions blank for this token.)

First, publish the package's config file.

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

Then, add the following entry to your .env file.

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

Usage

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();
    });
});

Allowing Dangerous Tags

By default, GitHub sanitizes HTML tags it deems "unsafe" like <iframe>s. However, it's common to embed video or audio into your markdown with <iframe>s.

GitDown can intelligently preserve your tags by filling the allowedTags config array option in config/gitdown.php with the tags you want to prevent being parsed.

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

Non-Laravel Usage

You can set a GitHub Personal Access Token by passing it into the GitDown's constructor. 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

Styling markdown with CSS has always been a bit of a pain for me. Not to mention trying to style syntax inside code blocks. Not to worry!

GitDown ships with all the CSS you need to make your markdown look exactly like it does on GitHub. Just add this code somewhere on your HTML page, preferably near your other stylesheets in the <head> section.

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

Non-Laravel

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

Bam! That's all you need to make everything look good 🤙.

If echoing out CSS directly on your page doesn't sit well with you, you can add the styles to your stylesheet yourself using NPM.

npm install primer-markdown github-syntax-light --save

Now you can include the SCSS files in your Sass bundler:

@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

To enable GFM parsing for GitDown, set the "context" entry in config/gitdown.php to a repository name.

"context" => "your/repo",

Enjoy!

Hope this makes your life easier. If it does, show the project some love on Twitter and tag me: @calebporzio

calebporzio/gitdown 适用场景与选型建议

calebporzio/gitdown 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 13.87k 次下载、GitHub Stars 达 217，最近一次更新时间为 2019 年 03 月 06 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「gitdown」「calebporzio」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 calebporzio/gitdown 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 calebporzio/gitdown 我们能提供哪些服务？

定制开发 / 二次开发

基于 calebporzio/gitdown 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 calebporzio/gitdown 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

calebporzio/awesome-helpers 629

Helper functions I find super-duper handy

coliving/awesome-helpers 0

Helper functions I find super-duper handy.

skizu/gitdown 0

Markdown parser for PHP based on the CommonMark spec with integration into git

calebporzio/gitdown

包简介

关键字：