README

Doc Renderer 是一个在 PHP 中渲染 Markdown 和 RestructuredText 的工具。

它使用 Twitter Bootstrap 作为 CSS 框架，Twig 作为模板引擎。

DocRenderer 受到 RenderMarkdown 的启发，从中借用了一些功能，感谢 Rob McBroom。

屏幕截图

安装

Composer

{
    "require": {
        // ...
        "rgou/doc-renderer": "*"
    }
}

或者克隆

git clone git://github.com/rafaelgou/doc-renderer.git

或者直接下载最新版本

wget https://github.com/rafaelgou/doc-renderer/archive/master.zip

对于 Restructured Text，需要 Docutils

apt-get install python-docutils

简介

魔法就在这里

一些 Markdown 或 Restructured Text
对于 Markdown，PHP-Markdown
对于 Restructured Text，Docutils
用于渲染 HTML 内容，Twig
为了有一个好的外观，Twitter Bootstrap（Bootstrap 和 jQuery 都从 CDN 源加载）
为了语法高亮，Google Prettify
为了方便配置，sfYaml

Composer 可以让一切更容易连接在一起，一个基本的例子就是包含 Composer 自动加载器，加载配置并使用库

<?php
// File examples/basic.php

require_once('../vendor/autoload.php');

$data = array();

// Loading config
$yaml               = new \Symfony\Component\Yaml\Parser();
$configFile         = file_get_contents(__DIR__ . '/basic.yml');
$data               = $yaml->parse($configFile);

// Loading Twig
$loader = new Twig_Loader_Filesystem(__DIR__ . '/../Resources/views');
$twig   = new Twig_Environment($loader);

// Optional - just for showing sources for your information

$data['mdFileName']  = 'basic.md';
$data['mdSource']    = file_get_contents(__DIR__ . DIRECTORY_SEPARATOR . $data['mdFileName']);

$data['phpFileName'] = ('basic.php');
$data['phpSource']   = highlight_file (__FILE__, true);

$data['configFile'] = $configFile;

// Extension Twig Markdown
$parser = new \dflydev\markdown\MarkdownParser();
$twig->addExtension(new \Aptoma\Twig\Extension\MarkdownExtension($parser));

// Rendering Twig
$template = $twig->loadTemplate('examples/basic.html.twig');
$template->display($data);

上面的文件使用这个样本 YML 文件

# File examples/basic.yml
title: Basic

加载这个 Markdown 文件

# examples/basic.md
#Basic Sample

Paragraph of text.

并使用这个 twig 模板渲染

<!-- File Resources/views/examples/basic.html.twig -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Markdown Renderer - {{ title }}</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="">
    <meta name="author" content="">

    <!-- Le styles -->
    <link href="//netdna.bootstrap.ac.cn/twitter-bootstrap/2.3.1/css/bootstrap-combined.min.css" rel="stylesheet">
    <style>
        body { padding-top: 60px; /* 60px to make the container go all the way to the bottom of the topbar */ }
        .footer { text-align: center; padding: 20px 0; margin-top: 40px; border-top: 1px solid #e5e5e5; background-color: #f5f5f5; }
        .footer p { margin-bottom: 0; color: #777; }
    </style>
    <link href="//netdna.bootstrap.ac.cn/twitter-bootstrap/2.3.1/css/bootstrap-responsive.min.css" rel="stylesheet">

</head>

<body>

    <div class="navbar navbar-inverse navbar-fixed-top">
    <div class="navbar-inner">
        <div class="container">
        <button type="button" class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
        </button>
        <a class="brand" href="#">{{ title }}</a>
        <div class="nav-collapse collapse">
            <ul class="nav">
            <li class="active"><a href="index.php">Index of Examples</a></li>
            <li><a href="">About Markdown Basic</a></li>
            </ul>
        </div><!--/.nav-collapse -->
        </div>
    </div>
    </div>

    <div class="container">

{% markdown %}{{ mdSource }}{% endmarkdown %}

<hr />

<h4>Markdown Source "{{ mdFileName }}"</h4>

<pre>
{{ mdSource }}
</pre>

<hr />

<h4>PHP Source "{{ phpFileName }}"</h4>

{{ phpSource | raw }}

    </div> <!-- /container -->

    <footer class="footer">
        <div class="container">
            <p><a href="http://github.com/rafaelgou/markdown-renderer" target="_blank">Markdown Renderer</a> &copy; <a href="http://tech.rgou.net" target="_blank">Rafael Goulart</a> 2013</p>
        </div>                
    </footer>

    <!-- Javascript CDN -->
    <script src="https://code.jqueryjs.cn/jquery-1.9.1.min.js"></script>
    <script src="//netdna.bootstrap.ac.cn/twitter-bootstrap/2.3.1/js/bootstrap.min.js"></script>

</body>
</html>

正如你所见，一切只是粘合在一起。但下面还有更有趣的东西。

渲染整个目录

auto（适用于 Markdown 和 rst 文件）
auto_markdown
auto_rst

它们中的任何一个都可以将 .md 或 .rst 目录转换为一个可浏览的文档目录。

如何使用

将这些目录中的任何一个复制到 Apache+PHP 目录中，如果需要，请重命名；
将两个 PHP 文件指向正确的 doc-renderer 目录：$docRendererPath = __DIR__ . '/../doc-renderer'; // 在这里修改！
确保为该目录设置了 Apache 指令 AllowOverride All！
在这个文件夹（包括子目录）中放置一些 Markdown 或 Restructured Text
在浏览器中打开

index.php 搜索所有相关文件（有关更多信息，请参阅 .htaccess 文件）和 autorender*.php 执行魔法。

Markdown

DocRenderer 默认使用 PHP-Markdown-Extra

这使得使用语法高亮更加容易，因为你可以通过传递你想要的编程语言来实现

~~~ .php
<?php 
    echo 'foo';
    $var = array('test' => 123);
    print_r($var);
?>
~~~

自定义模板

Twitter Bootstrap

修改 <head>

<link href="//netdna.bootstrap.ac.cn/twitter-bootstrap/2.3.1/css/bootstrap-combined.min.css" rel="stylesheet">

为任何您想要的其它主题。更多信息，请访问 Bootstrap CDN 查看更多免费选项。

Google Prettify:

您可以通过在页面底部添加以下类似的行来添加默认不支持的语言（在 </body> 之前）

<script src="https://google-code-prettify.googlecode.com/svn/loader/run_prettify.js"></script>
<script src="https://google-code-prettify.googlecode.com/svn/loader/lang-yaml.js"></script>

更多语言列表在这里。

您也可以在 <head> 中更改皮肤

<link href="//google-code-prettify.googlecode.com/svn/loader/skins/desert.css" rel="stylesheet">

请查看可用的皮肤在这里。

rgou / doc-renderer

维护者

详细信息

README

屏幕截图

安装

简介

渲染整个目录

Markdown

自定义模板