README

Symfony2 Bundle 用于构建基于 Markdown 的简单文档（感谢 KnpMarkdownBundle 和 KnpMenuBundle）。

Markdown 语法: cheatsheet

功能

• 基于文件系统，易于处理（创建 markdown 文件，请求 uri，即可！）
• 通过简单地解析 toc 文件（目录）来生成菜单（KnpMenu）
• 链接重写：链接可以相对于文档根目录绝对编写，包将重写这些链接以使其可通过公共 URL 访问
• 图像 URL 重写：包将图像发布到配置的路径并重写 URL，类似于链接

依赖

• KnpMarkdownBundle
• KnpMenuBundle

安装

• 通过 composer 安装包

...
"projektmotor/documentationbundle" : "~0.1",
...

• 在 AppKernel 中激活

// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // activate bundle in AppKernel
        new Pm\DocumentationBundle\PmDocumentationBundle(),
        
        // if not yet done
        new Knp\Bundle\MenuBundle\KnpMenuBundle(),
        new Knp\Bundle\MarkdownBundle\KnpMarkdownBundle(),
    );
}

• 包含路由

# e.g. app/config/routing.yml
pm_documentation:
    resource: "@PmDocumentationBundle/Resources/config/routing.yml"
    prefix:   /documentation

• 可选 - 设置文档根目录和模板（如果您不想使用默认路径）

# e.g. app/config/config.yml
pm_documentation:
    doc_path:   '/path/to/doc'
    image_dest: '/web/images/doc'
    view:       'AppBundle::layout.html.twig'

• 注意：模板（视图）必须包含一个名为 content 的块，其中渲染解析后的 Markdown。
• 注意：图像目标路径必须可由 web 服务器用户写入（例如 www-data）

用法

目录结构

• 假设您的文档根目录位于 /my/doc
• 第一级子目录将不同的语言分开
  • /my/doc/en
  • /my/doc/de
  • ...
• 语言目录之后的所有目录 必须 包含一个 index.md（见 请求页面）
• /my/doc/en/index.md
• /my/doc/en/chapter_1/index.md
• ...
• 语言目录 应该 包含一个 toc.md（根据您的菜单需求）
• /my/doc/en/toc.md
• /my/doc/de/toc.md
• ...

请求页面

假设您想在浏览器中渲染 Markdown 文件 /path/to/doc/en/chapter_1/first-steps.md，只需调用 http://example.com/documentation/en/chapter_1/first-steps。

结构

• documentation : 路由前缀（可以在路由中设置）
• en : 语言
• chapter_1/first_steps : Markdown 文件的路径

如果您请求的是文件夹而不是特定的 Markdown 文件，则使用文件夹的 index.md 文件。请求 http://example.com/documentation/en/chapter_1 将渲染 /path/to/doc/en/chapter_1/index.md

包含（子）菜单

• 将菜单辅助器注入到您的 Knp MenuBuilder 中

services:
    app.menu_builder:
        class: AppBundle\Menu\MenuBuilder
        arguments:
            - @knp_menu.factory
            - @pm_documentation.menu_helper

class MenuBuilder
{
    private $menuBuilderHelper;
    
    public function __construct(FactoryInterface $factory, MenuBuilderHelper $subMenuBuilder)
    {
        $this->factory = $factory;
        $this->menuBuilderHelper = $subMenuBuilder;
    }
}

• 添加基于 toc.md 的菜单

class MenuBuilder
{
  // ....
  public function createMainMenu(RequestStack $requestStack)
  {
      $menu = $this->factory->createItem('root');

      // adding documentation menu as submenu
      $menu->addChild('Documentation', array(...));
      $this->subMenuBuilder->buildDocumentationMenu($menu['Documentation']);

      // OR adding as first-level menu
      $this->subMenuBuilder->buildDocumentationMenu($menu);
  }
  
  // ....
}