• The behind the scenes process (the simplified version)
  • And the realtime viewer?
  • And how about the sidebar?
• A closer look under the hood (the technical version)

So how the h*ck does it work?

It's quite simple actually.
I designed the process to be as uncomplicated and straight forward as possible. You don't need to do any configuration or follow strict frontmatter rules or mess with routing.

Refresher on how to use the package
You simply place your markdown files in your project's resources/docs/ directory and run the Artisan laradocgen:build command and the package does the rest.

The behind the scenes process (the simplified version)#

So what happens under the hood then?

• The package scans the directory containing the Markdown files and puts them all into a collection object
• The static page builder then loops through the collection. In each loop it makes a request to the view controller.
• The controller constructs a MarkdownPage object and passes it to the Blade view.
  • The MarkdownPage class converts the Markdown into HTML. It also automatically generates a page title and slug from the markdown filename.
  • If you have enabled Torchlight the Torchlight middleware will make inject beautiful syntax highlighting.
• The builder then creates an HTML file with the HTML it fetched from the Blade view and stores it in the output directory.
• Finally the builder copies the images in the media directory to the output folder.

All in all, the entire process takes literally only around 3.4 seconds to generate 8 pages of static HTML. Pretty good if you ask me :)

And the realtime viewer?#

The realtime viewer offers a live preview with the Markdown generated on the fly.

It uses the same view controller as the builder but parses the Markdown before each request. If there is demand for it I may implement a caching system which would make the realtime viewer fast enough to be viable as a host for the actual documentation if you don't want to do the static hosting site.

By the way, the realtime viewer also includes automatic 404 handling.

And how about the sidebar?#

The top level headings link to the Markdown pages. They are created using the same collection of MarkdownPage objects.

By default the generated collection is sorted alphabetically which does not make much sense. So I created a micro-parser for YAML. Yes I know a lot of people hate YAML, but for this application I think you will agree that it is not too bad. In the spirit of keeping things stupidly simple, in order to rearrange the order of the sidebar items you just make write the page slugs in the order you want them

**The linkIndex.yml file is automatically created when you publish the package assets and looks like this **

1# resources/docs/linkIndex.yml
2Links:
3  - this-page-is-first
4  - next-is-this-one

The helper class that reads the YAML assigns a numerical index to each entry. The NavigationLink class stores this index. If a Markdown page is not present in the YAML file they get the priority 999 which puts them last.

Why use YAML and not just have a txt file? This way it makes it easy to expand the linkIndex to add stuff like metadata while in this stage still maintaining the same level of (low) complexity.

The sublevels are the Table of Contents generated by the Markdown parser. When you access the page JavaScript function edits the DOM to move the TOC to the sidebar.

• I am still working on a way to do this during the build process.

A closer look under the hood (the technical version)#

Let's dig deeper into how the package works. This may be extra useful if you are planning on contributing to the package.

Coming soon...(tm)