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!
comments powered by Disqus