PmDocumentationBundle

Symfony2 Bundle to build simple Markdown based documentations (thanks to KnpMarkdownBundle & KnpMenuBundle).

Markdown syntax: cheatsheet

Features

• filesystem based for simple handling (create markdown-file, request uri, ready!)
• generate menus (KnpMenu) by simply parsing a toc-file (table of content)
• link rewriting: links could be written absolute to documentation root, bundle rewrites these links to be accessable by public urls
• image url rewriting: bundle is publishing the images to the configured path and rewrites urls, similar to links

Dependencies

• KnpMarkdownBundle
• KnpMenuBundle

Install

• Install package via composer:

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

• Activate in 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(),
    );
}

• Include routing:

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

• OPTIONAL - Set documentation root dir & template (if you do not want to use the default path):

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

• NOTE: the template (view) MUST CONTAIN a block called content where the parsed markdown is rendered in.
• NOTE: image destination path must be writeable by the web server user (e.g. www-data)

Usage

Directory Structure

• let`s say your documentation-root is at /my/doc
• first level subdirectories divide different languages from each other
  • /my/doc/en
  • /my/doc/de
  • ...
• every dir behind the language-dirs MUST contain an index.md (see Requesting a Page)
• /my/doc/en/index.md
• /my/doc/en/chapter_1/index.md
• ...
• the language-dirs SHOULD contain a toc.md (depending on your need of a menu)
• /my/doc/en/toc.md
• /my/doc/de/toc.md
• ...

Requesting a Page

Assuming you want to render the markdown file /path/to/doc/en/chapter_1/first-steps.md in your browser, just call http://example.com/documentation/en/chapter_1/first-steps.

Structure:

• documentation : the route prefix (could be set in routing)
• en : the locale
• chapter_1/first_steps : path to markdown file

If you request a folder instead of specific markdown-file, the index.md file of the folder is used. Requesting http://example.com/documentation/en/chapter_1 would end up in rendering the /path/to/doc/en/chapter_1/index.md

Including the (Sub-) Menu:

• inject menu helper to you 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;
    }
}

• add menu (based on 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);
  }
  
  // ....
}