Using MkDocs with WPLib Box¶
While you certainly can install MkDocs on your host computer and use it with your WPLib Box project, hopefully you won't have to as we've implemented MkDocs within of WPLib Box.
MkDocs allows you to both dynamically serve documentation from Markdown files while you are writing your docs (just like you can dynamically serve PHP files from your web server), and then MkDocs allows you to build a static website from those Markdown files for hosting your docs on your web server.
Dynamically Serving Markdown¶
WPLib Box automatically serves the Markdown files contained in your project's
/mkdocs directory to
in your browser (or to whatever
docs. subdomain is created by
Vagrantfile when you add your own domain name in
Write docs in Markdown¶
MkDocs allows you to write rich documentation in Markdown — great for documenting reusable plugins and themes — that you can then version control!
and view using the MkDocs built-in server which WPLib Box automatically configures
to serve from your project's '`/mkdocs
in a root or subdirectory of your web server containing the HTML, CSS and images that comprise a static copy of your documentation.
/mkdocs.yaml file which you can learn how to configure here.
If you use our chosen default
material theme you can also learn to configure via customizations,
so to use it you first SSH into WPLib Box and then run your MkDocs command, for example:
vagrant ssh MkDocs install
Our implementation of MkDocs follows WPLib Box's philosophy of containerization and is thus implemented with our own Docker container.
MkDocs command is itself is a Bash script which is designed to invoke the MkDocs container and that script
can be found at
/opt/box/bin/mkdocs after you
vagrant ssh into WPLib Box.
mkdocsalmost always starts
mkdocs servewhich is not particularly useful, especially if you are trying to run
mkdocs --versionor similar. We plan to fix this very soon.
Some commands may have issues. If you find this to be the case please contact our support to let us know so we can address sooner than later.