README

这是一个简单的实用工具，用于帮助在网络上提供markdown内容。它为markdown文件目录提供了代码抽象，每个目录可以包含可选的YAML配置头。

需要注意的只有三个类：Repository、Directory和File。一个File只是封装了磁盘上的一个文件，并允许您独立于主要内容与配置头中的数据（如果存在）进行交互。Directory在某个基本路径下充当File对象的配置工厂。它会确保父目录中定义的配置可以逐级传递到文件。一个Repository也是一个目录，但您可以请求它包含的任意路径，并且它会确保包含的目录按需加载，以允许配置正确传递。

这个库不会将文件内容转换为实际的markdown - 请使用您喜欢的任何工具来执行此操作。

示例用法

以下是一些基本的示例用法。

<?php

//define repo at root directory of content, with some global configuration
//that will filter down to all contained pages/directories
$repo = new AC\Servedown\Repository(__DIR__."/blog", array('base_url' => 'http://example.com/blog), array(
    'file_extensions' => array("md", "markdown", "textile", "txt"),
    'hide_prefixes' => array("_"),
    'config_cascade_whitelist' => array('published'),
    'allow_index' => true,
    'index_name' => 'index',
));

//get a specific file
$item = $repo->getPath("2012/01/example-page.md");

//or a directory
$dir = $repo->getItem('2012/01);
foreach ($dir as $item) {
    if ($item->isDirectory()) {
        //load other containing files or something
    }
}

//get breadcrumb info, ideally to be used in a template
$breadcrumbData = $repo->getBreadcrumbData($item);
foreach ($breadcrumbData as $item) {
    $content .= sprintf("<a href='%s'>%s</a>", $item['url'], $item['title']);
}

//get some optional metadata, can contain whatever values you want
//to keep track of on a per-file basis
$title = $item->get('title', "Default Page Title");

//use some markdown parser to parse the page contents
$html = $yourFavoriteMarkdownParser->parse($item);

如果您使用此库将内容公开到网络上，请注意，如果您想图像正常工作，您需要使目录可公开访问。或者，您可以编写更多代码或实现自定义服务器配置。

仓库配置

每个仓库都有各种选项可以改变仓库的行为，以及它允许做什么。这些选项及其值可以通过仓库的构造函数传入。

• base_url - 如果提供，面包屑将包含引用文件的绝对URL。

请注意，在请求包含项的面包屑数据时，仓库将自动查找每个文件的title配置。如果不存在，它将把文件路径转换为更易于阅读的格式。

目录配置

目录也可以进行配置。当目录加载包含的目录时，其目录行为会逐级传递到子目录。这些是可用的选项

• file_extensions - 考虑为有效文件扩展名的数组。列表中不存在的扩展名的文件将被忽略。默认：array('md','markdown','txt','textile')
• hide_prefixes - 要忽略的前缀数组。任何以给定前缀开始的文件和目录都将被忽略。默认：array('_')
• config_cascade_whitelist - 配置键的数组，如果存在于目录索引文件中，将传递到所有子目录。默认：empty
• allow_index - 如果为true，这将允许文件作为目录的索引文件，这意味着目录级别的文件可以包含类似于任何其他页面的内容，并且可能包含将传递到同一目录中包含的其他文件的配置。默认：true
• index_name - 应作为索引的文件名称。扩展名可以是file_extensions配置中的任何有效扩展名。默认：index

示例内容

以下是一些内容和配置的示例。

示例页面

每个页面都可以包含一个YAML格式的元数据头。以下是一个包含配置的markdown页面示例。

````
title: An Example Page
published: true
````
# Hello World #

This is your typical markdown content.

示例目录覆盖

您还可以通过指定一个 index 文件来配置目录。例如，这可以指定在 index.md 中，该文件及其包含的所有文件和目录，都会从 $page->get('published'); 返回 false。虽然您可以选择不指定任何实际内容，但也可以指定。

````
published: false
````

潜在待办事项

• 硬配置与软配置级联