PHPackages                             gyvex-com/markdown-docs - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. gyvex-com/markdown-docs

ActiveLibrary

gyvex-com/markdown-docs
=======================

Render a configurable folder of markdown files as a browsable /docs site in Laravel, with nested path routing and an auto-generated sidebar.

00PHPCI passing

Since Aug 24Pushed todayCompare

[ Source](https://github.com/gyvex-com/markdown-docs)[ Packagist](https://packagist.org/packages/gyvex-com/markdown-docs)[ RSS](/packages/gyvex-com-markdown-docs/feed)WikiDiscussions main Synced today

READMEChangelog (1)DependenciesVersions (1)Used By (0)

Markdown Docs for Laravel
=========================

[](#markdown-docs-for-laravel)

Render a configurable folder of Markdown files as a browsable `/docs` site in Laravel - with nested path routing, an auto-generated sidebar, and front-matter driven navigation. No database, no build step: point it at a directory and it just works.

[![Latest Stable Version](https://camo.githubusercontent.com/21baaea326590445499dd5564fc2e6e762e3fd5b1bd53b7a82661ce1038025c7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f67797665782d636f6d2f6d61726b646f776e2d646f63732e737667)](https://packagist.org/packages/gyvex-com/markdown-docs)[![License](https://camo.githubusercontent.com/52002e5230472f8e47d554dc66b37d6ac9e165fff2828649fd018fbcb4f84e61/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f67797665782d636f6d2f6d61726b646f776e2d646f63732e737667)](https://packagist.org/packages/gyvex-com/markdown-docs)

Features
--------

[](#features)

- **Zero-config routing** - Every `.md` file under your docs folder becomes a route automatically. Subdirectories map to nested paths (`/docs/guides/installation`).
- **Auto-generated sidebar** - A navigation tree is built from your folder structure and front-matter `order`, so the menu stays in sync with your files.
- **Front matter** - Set `title` and `order` per page with a leading YAML block.
- **Customizable navigation** - Optionally replace the auto-generated sidebar with a hand-written menu via a `.docs.yaml` file.
- **Custom styling** - Ship your own stylesheet for the docs UI without overriding views.
- **Safe rendering** - GitHub-flavored Markdown via [`league/commonmark`](https://commonmark.thephpleague.com/), with unsafe HTML escaped and unsafe links disabled.
- **Caching** - Rendered HTML is cached keyed by file path + modification time, so pages only re-parse when the source changes.
- **Path-traversal protection** - Resolved files are guaranteed to live inside the configured docs root.

Requirements
------------

[](#requirements)

- PHP `^8.1`
- Laravel `^11 | ^12 | ^13` (`illuminate/*` components)

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require gyvex-com/markdown-docs
```

The service provider is auto-discovered by Laravel. If you have disabled package discovery, register `GyvexCom\MarkdownDocs\MarkdownDocsServiceProvider` manually.

Quick start
-----------

[](#quick-start)

1. Create a `docs/` folder at the root of your Laravel project:

    ```
    mkdir docs
    ```
2. Add a Markdown file named `index.md` (this becomes the landing page):

    ```
    # Welcome

    This documentation site is rendered from Markdown files.
    ```
3. Visit `/docs` in your browser.

Any other Markdown file you drop in (e.g. `docs/guides/installation.md`) is immediately available at `/docs/guides/installation`.

How routing works
-----------------

[](#how-routing-works)

The package registers a single catch-all route under your configured prefix:

```
GET /{prefix}/{path?}

```

The `{path}` segment is the relative path of a Markdown file (without the `.md` extension). Directory `index.md` files serve as the landing page of their folder, so a directory link stays clean (`/docs/guides` instead of `/docs/guides/index`).

File on diskURL`docs/index.md``/docs``docs/getting-started.md``/docs/getting-started``docs/guides/index.md``/docs/guides``docs/guides/installation.md``/docs/guides/installation`Configuration
-------------

[](#configuration)

Publish the config file to customize behavior:

```
php artisan vendor:publish --tag=markdown-docs-config
```

The published file lives at `config/docs.php`:

```
return [
    // Absolute path to the folder containing your .md files.
    'path' => base_path('docs'),

    // URL prefix under which docs are served. Empty string disables routing.
    'route_prefix' => 'docs',

    // Middleware applied to the docs routes.
    'middleware' => ['web'],

    // Filename (no extension) used for the root and per-directory landing pages.
    'index' => 'index',

    // Optional per-docs-folder YAML config (stylesheet + menu overrides).
    'config_file' => '.docs.yaml',

    // Cache rendered HTML, keyed by file path and mtime.
    'cache' => true,
];
```

### Protecting docs

[](#protecting-docs)

Because docs are public by default, restrict access by adjusting the `middleware` config - e.g. wrap the routes in `auth` or a custom gate:

```
'middleware' => ['web', 'auth'],
```

Front matter
------------

[](#front-matter)

Each Markdown file can start with a YAML front-matter block delimited by `---` lines:

```
---
title: Installation
order: 2
---

# Installation

Content goes here...
```

KeyTypeDescription`title`stringPage title used in the sidebar and ``. Falls back to the filename.`order`intSort order within its level. Directory index files default to `-1` (first).Customizing the sidebar (`.docs.yaml`)
--------------------------------------

[](#customizing-the-sidebar-docsyaml)

By default the sidebar is built from your folder structure. To define it explicitly, add a `.docs.yaml` file at your docs root:

```
stylesheet: styles/docs.css

menu:
  - title: Introduction
    url: /docs
  - title: Getting Started
    url: /docs/getting-started
    children:
      - title: Installation
        url: /docs/getting-started/installation
      - title: Configuration
        url: /docs/getting-started/configuration
  - title: Advanced
    url: /docs/advanced
```

- `stylesheet` - a path (served by the package's stylesheet route) that overrides the default UI styling.
- `menu` - a nested list of `title` / `url` / `children` items. When present, it replaces the auto-generated tree.

Customizing the views
---------------------

[](#customizing-the-views)

You can override the Blade views instead of (or in addition to) the stylesheet:

```
php artisan vendor:publish --tag=markdown-docs-views
```

The published views appear in `resources/views/vendor/markdown-docs/` and use the `markdown-docs::` namespace:

- `layout.blade.php` - the HTML shell, sidebar, and embedded CSS.
- `docs.blade.php` - the content section wrapper.
- `partials/sidebar.blade.php` - the navigation tree renderer.
- `partials/sidebar-item.blade.php` - a single (recursive) navigation node.

Programmatic usage
------------------

[](#programmatic-usage)

The `MarkdownDocs` facade (or the `markdown-docs` container binding) exposes the underlying manager:

```
use MarkdownDocs;

// Resolve a doc by path (without .md), or null if missing.
$doc = MarkdownDocs::resolve('guides/installation');

// Rendered HTML for a doc.
$html = MarkdownDocs::render($doc);

// The navigation tree (array of nodes with title/url/order/children).
$tree = MarkdownDocs::tree();
```

The bound manager is also available as `GyvexCom\MarkdownDocs\MarkdownDocsManager`.

Testing
-------

[](#testing)

The package uses [Orchestra Testbench](https://packages.tools/orchestra-testbench/) and PHPUnit:

```
composer test
```

Security
--------

[](#security)

- HTML input in Markdown is escaped and unsafe links are disabled by default.
- The filesystem repository validates that every resolved file lives inside the configured docs root, preventing path-traversal.

License
-------

[](#license)

Markdown Docs for Laravel is open-sourced software licensed under the [MIT license](LICENSE).

###  Health Score

21

—

LowBetter than 17% of packages

Maintenance65

Regular maintenance activity

Popularity0

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor2

2 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/98355868?v=4)[Gyvex](/maintainers/gyvex-com)[@gyvex-com](https://github.com/gyvex-com)

---

Top Contributors

[![NielsHamelink-web](https://avatars.githubusercontent.com/u/67690385?v=4)](https://github.com/NielsHamelink-web "NielsHamelink-web (2 commits)")[![ns-climate-nl](https://avatars.githubusercontent.com/u/299178487?v=4)](https://github.com/ns-climate-nl "ns-climate-nl (2 commits)")[![Shadow48402](https://avatars.githubusercontent.com/u/4586181?v=4)](https://github.com/Shadow48402 "Shadow48402 (1 commits)")

### Embed Badge

![Health badge](/badges/gyvex-com-markdown-docs/health.svg)

```
[![Health](https://phpackages.com/badges/gyvex-com-markdown-docs/health.svg)](https://phpackages.com/packages/gyvex-com-markdown-docs)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)