laravelista / sherlock
Deduct a markdown document and get a specific chapter and/or a table of content.
Requires
- php: >=7.0.0
- tightenco/collect: ^5.2
- twig/twig: ~1.0
Requires (Dev)
- phpspec/phpspec: ^3.1
README
Sherlock is a PHP package that provides unique features for markdown.
It can create a Table of Content or retrieve a specific chapter.
Overview
I use this package on my website Laravelista to create table of content for my lessons, posts and packages. Also, I use it to provide free samples of my lessons.
Get the Table of Content
Given this markdown:
# Book Title ## Chapter 1 This is chapter *one*. ## Chapter 2 This is chapter two.
You can generate a table of content:
use Laravelista\Sherlock\Sherlock; $sherlock = new Sherlock; return $sherlock->deduct($markdown)->getToc();
HTML Output:
<ul class="sherlock-toc"> <li><a href="#book-title">Book Title</a> <ul> <li><a href="#chapter-1">Chapter 1</a></li> <li><a href="#chapter-2">Chapter 2</a></li> </ul> </li> </ul>
Get a specific chapter
Given the same markdown as in the sample above we can fetch a specific chapter from our markdown documents by its name.
use Laravelista\Sherlock\Sherlock; $sherlock = new Sherlock; return $sherlock->deduct($markdown)->get('Chapter 1');
Markdown output:
This is chapter *one*.
Laravel usage inside views
If you are using Laravel, there is a convenient way of loading Sherlock in your views. At the top of your view file where you want to display the Table of Content add this code to inject Sherlock and deduct the content:
@inject('sherlock', 'Laravelista\Sherlock\Sherlock')
<?php $sherlock->deduct($lesson->content) ?>
And then in the place where you want to display the actual Table of Content add this:
{!! $sherlock->getToc() !!}
or to get a specific chapter use $sherlock->get(). Just remember that get() returns markdown, so be sure to parse the markdown to HTML.
Installation
From the command line:
composer require laravelista/sherlock
API
deduct
Reads given markdown string and generates an index of the document (Library).
$sherlock->deduct(string $content)
You can chain this method with other methods from the API, but this method must always be called first. Library can be retrieved if needed with getLibrary().
getToc
Returns the Table of Content in HTML format.
$sherlock->deduct($markdown)->getToc()
Example:
Given this markdown:
# Book Title ## Chapter 1 This is chapter *one*. ## Chapter 2 This is chapter two.
it returns this HTML output:
<ul class="sherlock-toc"> <li><a href="#book-title">Book Title</a> <ul> <li><a href="#chapter-1">Chapter 1</a></li> <li><a href="#chapter-2">Chapter 2</a></li> </ul> </li> </ul>
get
Returns markdown for specific chapter.
$sherlock->deduct($markdown)->get('Chapter 1')
Example:
Given this markdown:
# Book Title ## Chapter 1 This is chapter *one*. ## Chapter 2 This is chapter two.
it returns this Markdown output:
This is chapter *one*.
getLibrary
It returns the index of the document (Library); which was deducted from the given markdown in deduct() method; as an array.
$sherlock->deduct($markdown)->getLibrary()
Example:
This is a sample of the Library you get:
[
[
'level' => 1,
'name' => 'This is the document title',
'starts_at' => 0,
'ends_at' => 3,
'slug' => 'this-is-the-document-title'
],
[
'level' => 2,
'name' => 'Introduction',
'starts_at' => 4,
'ends_at' => 7,
'slug' => 'introduction'
],
[
'level' => 3,
'name' => 'Another introduction',
'starts_at' => 8,
'ends_at' => 11,
'slug' => 'another-introduction'
],
[
'level' => 4,
'name' => 'Deep introduction',
'starts_at' => 12,
'ends_at' => 19,
'slug' => 'deep-introduction'
],
[
'level' => 2,
'name' => 'Plot',
'starts_at' => 20,
'ends_at' => 23,
'slug' => 'plot'
],
[
'level' => 2,
'name' => 'Conclusion',
'starts_at' => 24,
'ends_at' => 27,
'slug' => 'conclusion'
],
];
With it you can do all sorts of things.