Sharp doc reader

Display a directory of Markdown files as docs inside Sharp: a list of docs, and a page for each one with its table of contents.

Supports Sharp 9 and 10.

Installation

composer require code16/sharp-doc-reader

Optionally, publish the config file:

php artisan vendor:publish --tag="sharp-docs-config"

Usage

Create an entity extending DocsEntity, and give it the path of your Markdown files:

namespace App\Sharp\Entities;

use Code16\SharpDocs\Sharp\DocsEntity;

class AdminDocsEntity extends DocsEntity
{
    protected string $label = 'Docs';

    protected function docsPath(): string
    {
        return base_path('docs/sharp');
    }
}

There is no list or show class to write. Then declare the entity as any other Sharp entity (discoverEntities() or declareEntity()), and add it to your menu:

$menu->addEntityLink(AdminDocsEntity::class, 'Docs');

Several docs sets

Create one entity per docs set: each has its own path, label, menu entry and policy.

class UserDocsEntity extends DocsEntity
{
    protected string $label = 'User guide';
    protected ?string $policy = UserDocsPolicy::class;

    protected function docsPath(): string
    {
        return base_path('docs/users');
    }
}

Docs files

• Every .md file of the path is a doc, subfolders included (the list shows the folder).
• The title is the title of the front-matter if any, else the first # h1, else the headline of the file name.
• The first h1 is the page title and is not repeated in the content; the other headings move up a level (## is rendered as a <h1>), and the <h1> ones make the table of contents.
• Docs are sorted by folder, then by order (front-matter), then by title.
• A guides/index.md file is the guides doc: its files (e.g. images) can live next to it.
• Relative images (![](img/screenshot.png)) are resolved from the folder of the doc and served by the package route.
• Relative links to another doc's file ([install](../install/index.md#usage)) lead to the show page of that doc (and to its #usage heading).

---
title: Getting started
order: 1
---

# Ignored when the front-matter has a title

## Installation
...
![Screenshot](images/screenshot.png)

The doc ids are the path of the file without extension, / being replaced by . (guides/install.md is guides.install, guides/index.md is guides).

Images route

The files are served by GET /{sharp url segment}/docs-files/{entityKey}/{path}, only for files inside the entity's docs path. The prefix and the middleware can be changed in the config file; by default only logged-in Sharp users can access it.

Markdown rendering

The rendering uses league/commonmark. Options are set in the markdown key of the config file, or per entity:

protected function markdownOptions(): array
{
    return [
        // CommonMark configuration, merged over the defaults
        'commonmark' => ['html_input' => 'strip'],
        // Additional CommonMark extensions (instances or class names)
        'extensions' => [\League\CommonMark\Extension\Attributes\AttributesExtension::class],
        // Set to false to keep the headings as they are, the first h1 included
        'title_from_h1' => false,
    ];
}

By default raw HTML is allowed (html_input: allow): only point the entities to docs you trust, or set it to strip.

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.