GitHub docs should be readable

Automatically keep your documentation in order with VuePress

Jane Elizabeth
© Shutterstock / bulgakovaaleksa

GitHub projects live and die based on how good their documentation is. If a developer can’t read the repo, then they are going to find an alternative. Thanks to VuePress, it’s easier than ever to automatically update your documentation.

No one really likes updating their documentation. Yet, study after study proves that developers notice when a project’s documentation is bad. This is where VuePress comes in handy.

VuePress is a Vue-powered static site generator with a minimal and simplistic setup. More importantly, one of its main use cases is to make documentation automatically. It was originally designed to support Vue’s documentation needs.

So, how does VuePress work?

Basically, a VuePress site is a SPA backed by Vue, Vue Router, and webpack.

When VuePress generates a page, it also creates a pre-rendered static HTML to provide each one with an excellent loading performance. Once loaded, Vue takes over and turns the static content into a single-page application. Other pages are fetched on demand only when the user navigates around the site.

Inspired by Nuxt, VuePress creates a server-rendered version of the app during the build. The corresponding HTML is then rendered by virtually going through each route. Markdown files are compiled into the HTML and then processed as a templete of a Vue component. Developers are able to directly use Vue in these markdown files, making it easy to embed dynamic content.

SEE ALSO: Vue.js vs React poll results: Vue.js ready to slay its competition

What kind of features does VuePress offer developers?

For such a minimal setup, VuePress offers developers a whole host of features, including built-in markdown extensions optimized for technical documentation, the ability to leverage Vue inside markdown files, Google Analytics Integration, and more.

Most important, of course, is its ability to make GitHub documentation. With the markdown files that VuePress makes automatically, information emphasis and hierarchy are preserved in both the plaintext and rendered HTML file.

Relative links to other markdown files are automatically preserved, making it easy to keep everything organized without doing a lot of secretarial work. For example, if someone is viewing the GitHub version of the documentation, those links keep you on GitHub; the same link on the VuePress site takes you to the correct destination.

Additionally, VuePress is hands-off when it comes to the codebase! It stores any files in a .vuepress file, completely separate from the rest of your code. It only looks exclusive for markdown files when building a site, keeping VuePress from building something in the wrong place by accident.

SEE ALSO: Vue CLI 3.0 is here: Less configuring, more coding

Getting VuePress

Getting VuePress is simple. It only requires a few lines of code and a version of Node.js higher than 8.

More information about this innovative approach towards documentation is available here.

Jane Elizabeth
Jane Elizabeth is an assistant editor for

Inline Feedbacks
View all comments