Documentation (especially good documentation) for an application can make a good application and experience for a client, a great application. Once we as developers complete an application that we have worked and potentially even lost sleep over, will live on well after we stop working on it. Despite our best efforts, clients and customers tend to forget things that we show them on how to manage their application. That's where documentation comes in.
I'll come right out and say it: I hate writting documentation; regardless for what it is for. My normal avenue's of implementation documention are via Word document, or even a repository wiki. Recently I even used this awesome documentation package called LaRecipe, that I thorougly enjoyed using. However these solutions didn't solve my pain point of the documentation isn't all in the same place. It required a client to open up another application or web browser and comb through a few different pages. It was these issues that was the inspiration behind a new Nova tool that I built to solve.
So like I said, to solve my own pain, I built a new Laravel Nova tool called Nova Documentation (creative name right?).
What this tool essentially does is convert Markdown files and then passes them to the Vue component within the tool. Ultimately it is that simple, however there are a few other things that I added that I think will be useful:
Syntax highlighting to code blocks (thanks to highlight.js)
Dynamic navigation/table of contents
Document nesting with url rewriting
Flexible configuration settings
Installation
To start, lets install the Nova tool with:
composer require dniccum/nova-documentation
Next, we need to publish the tool's configuration file and a couple markdown files with examples to get you started:
php artisan vendor:publish --provider="Dniccum\NovaDocumentation\ToolServiceProvider"
By default, the sample markdown files that the tool uses to render it's content will be added to resources/documentation path. If you would like to move this directory, be sure to update this setting within the config/novadocumentation.php configuration file:
/*
|--------------------------------------------------------------------------
| Home Page
|--------------------------------------------------------------------------
|
| The markdown document that will be used as the home page and/or entry
| point. This will be located within the documentation directory that resides
| within your application's resources directory.
|
*/
'home' => 'documentation/home.md',
And finally, just like every other Nova tool, we need to register the tool within the NovaServiceProvider:
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,
];
}
Assuming that you have done everything correctly, you should see a "Documentation" link in your Nova sidebar with this as a homepage:
Assuming that you are using the default installation configuration, the directory where all of the markdown file will be stored in the resources/documentation directory. Again, if you use the default settings, the home.md file that will be found there will represent the home page:
# Welcome to your documentation
Within this area, you can:
* Define features
* Add how-to's
* Link to tutorial videos/images
To see any other Markdown syntax and examples, please see [the sample](sample.md).
Generating your content
A few things you should note:
Any and all markdown is allowed in these markdown files.
You should be able to add any other HTML that you want to render within the page; excluding any Javascript as I am using Vue.js template compiler to build the page and any Javascript-based content probably won't render correctly.
I did add the necessary CSS to clean up some of the appearance of standard HTML tags like ordered/un-ordered lists, headers, block quotes, etc from the base stylesheet that Taylor Otwell constructed for the Nova dashboard. If you happen to find something that isn't quite styled correctly, drop me a line on the issues page on Github.
Feel free to organize your markdown files as you wish; whether everything is in the base directory or if you would like to add files within directories. The tool will detect them and build their url's accordingly.
Setting your titles
It is important to note that the H1 tags within each of these files will be dynamically pulled to build the sidebar navigation. With that said, make sure your titles are descriptive yet short in length to prevent the sidebar from becoming cluttered.
Other features?
As you continue to work with this tool, let me know if there are any other features that you would like to add. Thank you for your interest!
