VuePress Quickstart

Starter template for a VuePress project - including CI for GH Pages hosting

Preview

About

A template for a site made with VuePress, a Vue-based static site generator.

This means you can focus on your Markdown content rather than HTML code. And also Google can crawl your site easily because it's all statically rendered content (unlike the traditional SPA approach for a Vue or React app which has poor SEO support).

This project includes a flow to use GitHub Actions for CI, so you can get a auto-deploying GitHub Pages site for free.

This is great for turning a docs directory into a docs site. Or you can have a branched called docs which is independent of your main branch, to keep your app and docs independent.

Start your VuePress project

Get a project like this one by clicking the button.

Then follow the Installation and Usage instructions below.

Why VuePress?

Build a modern, static website using markdown for content. Great for a docs site.

From the homepage:

Simplicity First - Minimal setup with markdown-centered project structure helps you focus on writing.

Vue-Powered - Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.

Performant - VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.

To learn more about VuePress, the Vuerpress homepage or my my Vuepress resources page.

The default site generated by VuePress CLI (and included in this template project) comes with a theme configured already. But you can install and configure other themes as per the Theme Configuration docs section.

Create a fresh project

Here is how to the VuePress CLI tool to bootstrap a new project in a local directory.

Make sure you have Node.js 10+ installed and Yarn, if used below.

These commands will work even if you don't have VuePress installed locally.

Using NPM / NPX:
```
$ npx create-vuepress-site my-app
```
Using Yarn:
```
$ yarn create vuepress-site my-app
```

Then navigate to the app.

$ cd my-app
$ cd docs

Installation

Install system dependencies

Install Node.js and Yarn - see instructions.

Clone

Create a new project from this template or the template repo.

Clone the repo:

$ git clone git@github.com:MichaelCurrin/vuepress-quickstart.git
$ cd vuepress-quickstart

Install project packages

All the content is in docs, so navigate there.

$ cd docs

Install NPM packages with YRN.

$ yarn install

Usage

$ cd docs

Server

Start a dev server.

$ yarn dev

Deploy

Build

Build the site to an output directory.

$ yarn build

The output path will be at docs/src/.vuepress/dist/.

That output can then be served as static content of for a website.

CI

If you use a CI tool, you can have that build step happen in the cloud on a commit.

For GitHub Actions, you can build the site and commit the result to gh-pages branch, which can be served with GitHub Pages. See docs.yml workflow.

Commit and push your repo.
View the Actions tab to check that that build pages.
Go to your repo's Settings.
Enable GitHub Pages - for the project root on the gh-pages branch.
View your site. e.g. https://michaelcurrin.github.io/vuepress-quickstart/

This project is setup to serve as a subpath on GitHub Pages, using base as per the Config page of the docs. This is setup in config.js.

For a Netlify site, you can configure the site the build command and target directory. See my Configure guide.

Related projects

- Template for a docs site made with Docsify, which is built on Vue. Config is even lighter than VuePress and there's no build step! Note that Docsify follows the SPA style, so you won't get the SEO benefits of a static site like with VuePress. Also, themes are limited in Docsify.
- Template for a static made with Nuxt, which is built on Vue.
- Template for a Node app using Vue.

License

Released under MIT by @MichaelCurrin.