Introduction
VuePress is composed of two parts: a minimalistic static site generator with a Vue-powered theming system, and a default theme optimized for writing technical documentation. It was created to support the documentation needs of Vue's own sub projects.
Each page generated by VuePress has its own pre-rendered static HTML, providing great loading performance and is SEO-friendly. Once the page is loaded, however, Vue takes over the static content and turns it into a full Single-Page Application (SPA). Additional pages are fetched on demand as the user navigates around the site.
How It Works
A VuePress site is in fact a SPA powered by Vue, Vue Router and webpack. If you've used Vue before, you will notice the familiar development experience when you are writing or developing custom themes (you can even use Vue DevTools to debug your custom theme!).
During the build, we create a server-rendered version of the app and render the corresponding HTML by virtually visiting each route. This approach is inspired by Nuxt's nuxt generate command and other projects like Gatsby.
Each markdown file is compiled into HTML with markdown-it and then processed as the template of a Vue component. This allows you to directly use Vue inside your markdown files and is great when you need to embed dynamic content.
Features
- Built-in markdown extensions optimized for technical documentation
- Ability to leverage Vue inside markdown files
- Vue-powered custom theme system
- Automatic Service Worker generation
- Google Analytics Integration
- "Last Updated" based on Git
- Multi-language support
- A default theme with:
- Responsive layout
- Optional Homepage
- Simple out-of-the-box header-based search
- Algolia Search
- Customizable navbar and sidebar
- Auto-generated GitHub link and page edit links
Todo
VuePress is still a work in progress. There are a few things that it currently does not support but are planned:
- Plugin support
- Blogging support
Contributions are welcome!
Why Not ...?
Nuxt
Nuxt is capable of doing what VuePress does, but it is designed for building applications. VuePress is focused on content-centric static sites and provides features tailored for technical documentation out of the box.
Docsify / Docute
Both are great projects and also Vue-powered. Except they are both completely runtime-driven and therefore not SEO-friendly. If you don't care about SEO and don't want to mess with installing dependencies, these are still great choices.
Hexo
Hexo has been serving the Vue docs well - in fact, we are probably still a long way to go from migrating away from it for our main site. The biggest problem is that its theming system is very static and string-based - we really want to leverage Vue for both the layout and the interactivity. Also, Hexo's markdown rendering isn't the most flexible to configure.
GitBook
We've been using GitBook for most of our sub project docs. The primary problem with GitBook is that its development reload performance is intolerable with a large amount of files. The default theme also has a pretty limiting navigation structure, and the theming system is, again, not Vue based. The team behind GitBook is also more focused on turning it into a commercial product rather than an open-source tool.