PHPackages                             marshmallow/nova-documentation - 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. [Utility & Helpers](/categories/utility)
4. /
5. marshmallow/nova-documentation

ActiveLibrary[Utility & Helpers](/categories/utility)

marshmallow/nova-documentation
==============================

A Laravel Nova tool that allows you to add markdown-based documentation to your administrator's dashboard.

025PHP

Since Feb 8Pushed 1y agoCompare

[ Source](https://github.com/marshmallow-forks/nova-documentation)[ Packagist](https://packagist.org/packages/marshmallow/nova-documentation)[ RSS](/packages/marshmallow-nova-documentation/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

[![Documentation tool for Laravel Nova](https://github.com/dniccum/nova-documentation/raw/master/screenshots/nova-documentation-social-image.png?raw=true)](https://github.com/dniccum/nova-documentation/blob/master/screenshots/nova-documentation-social-image.png?raw=true)

[![Latest Version on Packagist](https://camo.githubusercontent.com/f62dad022c504d3aee224b5c4044f64ceebb949ffd44e63c5eb14f07b7c75b57/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f646e696363756d2f6e6f76612d646f63756d656e746174696f6e2e7376673f7374796c653d666c61742d73717561726526636f6c6f723d23304537464330)](https://packagist.org/packages/dniccum/nova-documentation)[![License](https://camo.githubusercontent.com/d4df73f3267465847c3846c5be8070e8b08567af9ee57cbfa782c65e79d1144c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f646e696363756d2f6e6f76612d646f63756d656e746174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/dniccum/nova-documentation)[![Total Downloads](https://camo.githubusercontent.com/fdb7ffda5f931f99c422db0ec250c73e12214c80f181ae8f0b85e5e2e6479f2d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f646e696363756d2f6e6f76612d646f63756d656e746174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/dniccum/nova-documentation)

This is a tool for Laravel's Nova administrator panel that allows you to create markdown-based documentation for your application; without having to leave the Nova environment.

[![Screenshot](https://raw.githubusercontent.com/dniccum/nova-documentation/master/screenshots/screenshot-1.png)](https://raw.githubusercontent.com/dniccum/nova-documentation/master/screenshots/screenshot-1.png)

Table of Contents
-----------------

[](#table-of-contents)

- [Compatibility Note](#compatibility-note)
- [Features](#features)
- [Installation](#installation)
- [Upgrading from version 2](#upgrading-from-version-2)
    - [Add YAML configuration](#add-yaml-configuration)
    - [Set environment variable](#set-environment-variable)
    - [Remove dashed horizontal rules](#remove-dashed-horizontal-rules)
- [Using this tool](#using-this-tool)
    - [Page YAML configuration/customization](#page-yaml-configurationcustomization)
        - [Adding configuration to your pages](#adding-configuration-to-your-pages)
    - [Linking](#linking)
        - [Relative links](#relative-links)
        - [Other types](#other-types)
    - [Routes and adding new pages](#routes-and-adding-new-pages)
    - [Authorization redirects](#authorization-redirects)
- [Configuration](#configuration)
- [License](#license)
- [Credits](#credits)

Compatibility Note
------------------

[](#compatibility-note)

Please note, this plugin now **only supports Laravel Nova v4**. If you are using Laravel Nova <= v3, please use version `^3.0`,

Features
--------

[](#features)

- Parses each markdown document and renders them in the Nova dashboard
- Dynamic page titles: Each h1 tag (`# title`) is set as the page title
    - Each page title is then used to construct a sidebar, allowing for navigation through your documentation.
    - Allows for nested directories
- Supports YAML parsing to further customize page titles
- Syntax highlighting for code blocks (via [highlight.js](https://highlightjs.org/))
- Replaces local links within the body content to work within the Nova environment.
- Supports both browser light and dark themes.
- Allows for customized login/authorization redirection logic if you want to customize what users see if they are not appropriately authenticated.

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

[](#installation)

You can install the package via composer:

```
composer require dniccum/nova-documentation

```

You will then need to publish the package's configuration and blade view files to your applications installation:

```
php artisan vendor:publish --provider="Dniccum\NovaDocumentation\ToolServiceProvider"

```

Finally, you will need to register the tool within the `NovaServiceProvider.php`:

```
use Dniccum\NovaDocumentation\NovaDocumentation;

...

/**
 * Get the tools that should be listed in the Nova sidebar.
 *
 * @return array
 */
public function tools()
{
    return [
        // other tools
        new NovaDocumentation,
    ];
}
```

Upgrading from version 2
------------------------

[](#upgrading-from-version-2)

If you are upgrading from version 2 to version 3 (Laravel Nova 4 support), make sure your `composer.json` has the following version/reference to included the updated version:

```
"dniccum/nova-documentation": "^3.0"

```

### Add YAML configuration

[](#add-yaml-configuration)

If you published the configuration from this package using the `vendor:publish` command, you will need to add the following code your `novadocumentation.php` configuration file's array:

```
'parser' => env('NOVA_DOCUMENTATION_PARSER', 'yaml'),
```

### Set environment variable

[](#set-environment-variable)

If you are planning on not refactoring your markdown files to *NOT* take advantage of the new YAML configuration options, you will need to either modify your configuration file accordingly, or simply set the following environment variable:

```
NOVA_DOCUMENTATION_PARSER=markdown
```

### Remove dashed horizontal rules

[](#remove-dashed-horizontal-rules)

If you have any `---` horizontal rules in your markdown files and your are using the `yaml` parser, you will need to convert those to use `***` instead as this will cause the YAML processing to error.

Using this tool
---------------

[](#using-this-tool)

- After all of this tool's assets have been published, there should be two `.md` (markdown) files placed within a documentation directory at the base of your `resources` directory.
    - If you would like to change this directory, change the `config('novadocumentation.home')` configuration definition.
    - By default, the "home page" entry point is `home.md`. Again if you would like to change that, be sure that you alter the `config('novadocumentation.home')` configuration.
- If using the markdown setup, the sidebar navigation is constructed using two different elements: the name of the file and the title of within the file. This title is dynamically pulled from the first `# title` in each file.

### Page YAML configuration/customization

[](#page-yaml-configurationcustomization)

If you are using the `yaml` parsing method, you have the **OPTIONAL** ability to customize how each page is built and shown within the sidebar. You can modify the following attributes:

- title - The title of the page within the sidebar
- path - The path/route/link of the page. Provide a valid URL
- order - The order in which this page will appear in the sidebar

#### Adding configuration to your pages

[](#adding-configuration-to-your-pages)

If we wanted to customize a page of documentation we would need to add the following content to the top of the page:

```
---
title: "Adding Content"
path: content
order: 2
---

# Adding content to your application

...
```

The important thing to note is the `---` element wrapping the configuration. **This will not work if this is not in place.** The title should be pretty self-explanatory. The path allows you to customize the route to the page.

### Linking

[](#linking)

If you would like to link to other markdown files within your body content, outside of the sidebar, be sure to use **relative links** that **DO NOT** begin with a forward slash, like so `/relative`. For example if you are linking from the home page to a sub-directory based file called authentication, you would link to it like so:

```
[authentication](authentication/base.md)
```

The tool will dynamically replace this link.

#### Relative links

[](#relative-links)

If you would like to include a relative link to another location within your application or Nova itself, include a link that is prefixed with a forward slash (`/`), like so:

```
[terms and services](/terms-and-services)
```

#### Other types

[](#other-types)

Other types of links that are supported:

- Mailto (`mailto:`) links
- External http and https links

### Routes and adding new pages

[](#routes-and-adding-new-pages)

When a new document is added to the application architecture, and if your application leverages route caching, **be sure to clear/reset your route cache accordingly** (`php artisan route:clear`).

### Authorization redirects

[](#authorization-redirects)

If desired, you can specify where an un-authenticated user is redirected if they attempt to access the module. To do so, modify the `novadocumentation.login_route` setting and set it to a valid route within your application.

Configuration
-------------

[](#configuration)

The configuration items listed below can be found in the `novadocumentation.php` configuration file.

```