Using your project docs inside the application

The applications I work on have markdown docs. These can be in the docs/ folder for example as docs/webhooks.md

But some of these docs have value to the user of the UI not just the developer, and when we include these docs inside the application repo it is a TON easier to just update them as you fix and make new features in the codebase.

You can have the best of both worlds with a simple to use library https://github.com/michelf/php-markdown

The Controller

This then allows me, in my controllers to get some content from these docs, for example

<?php

namespace App\Http\Controllers;


use App\Http\Requests;
use Michelf\MarkdownExtra;

class HelpController extends Controller
{
    public function api()
    {
        $text = file_get_contents(base_path('docs/webhooks.md'));
        $webhooks = MarkdownExtra::defaultTransform($text);

        return view('help.api', compact('webhooks'));
    }
}

The Blade Template File

Then in the blade template all I need to do to show those docs are

@extends('layouts.default')

@section('content')

    <div class="page-header">
        <h1>API Help</h1>
    </div>

    <div class="row">
        <div class="col-lg-12">
            <div class="wrapper wrapper-content animated fadeInRight">
                <div class="ibox-content">
                    {!! $webhooks !!}
                </div>
            </div>
        </div>
    </div>

@endsection

Being a private repo we review the code so using “{!!” is not so bad. But keep in mind you are trusting what is in these files! Of course a simple

$webhooks = strip_tags($webhooks, "tags you allow here");

Will help out there.

The Markdown

Then just write your file as normal in markdown!