https://github.com/michaelcurrin/vuepress-quickstart
Starter template for a VuePress project - including CI for GH Pages hosting
https://github.com/michaelcurrin/vuepress-quickstart
docs-site gh-pages-site github-pages-website nodejs starter template vue vuepress
Last synced: 11 months ago
JSON representation
Starter template for a VuePress project - including CI for GH Pages hosting
- Host: GitHub
- URL: https://github.com/michaelcurrin/vuepress-quickstart
- Owner: MichaelCurrin
- License: mit
- Created: 2020-10-28T12:21:42.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2021-10-30T08:00:21.000Z (over 4 years ago)
- Last Synced: 2025-01-14T20:51:43.915Z (about 1 year ago)
- Topics: docs-site, gh-pages-site, github-pages-website, nodejs, starter, template, vue, vuepress
- Homepage: https://michaelcurrin.github.io/vuepress-quickstart/
- Size: 688 KB
- Stars: 3
- Watchers: 4
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# VuePress Quickstart
> Starter template for a VuePress project - including CI for GH Pages hosting
[](https://github.com/MichaelCurrin/vuepress-quickstart/actions?query=workflow:"Deploy+docs")
[](https://github.com/MichaelCurrin/vuepress-quickstart/releases/)
[](#license)
[](https://nodejs.org)
[](https://classic.yarnpkg.com)
[](https://www.npmjs.com/package/vuepress)
## Preview
[](https://michaelcurrin.github.io/vuepress-quickstart/)
## 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.
[](https://github.com/MichaelCurrin/vuepress-quickstart/generate)
Then follow the [Installation](#installation) and [Usage](#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](https://vuepress.vuejs.org/) homepage or my my [Vuepress resources](https://michaelcurrin.github.io/dev-resources/resources/javascript/packages/vuepress/) 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](https://v1.vuepress.vuejs.org/theme/option-api.html) docs section.
## Create a fresh project
Here is how to the VuePress CLI tool to bootstrap a new project in a local directory.
- [](https://github.com/vuepress/create-vuepress-site)
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:
```sh
$ npx create-vuepress-site my-app
```
- Using Yarn:
```sh
$ yarn create vuepress-site my-app
```
Then navigate to the app.
```sh
$ cd my-app
$ cd docs
```
## Installation
### Install system dependencies
Install Node.js and Yarn - see [instructions](https://gist.github.com/bdc34c554fa3023ee81449eb77375fcb).
### Clone
Create a new project from this template or the template repo.
Clone the repo:
```sh
$ git clone git@github.com:MichaelCurrin/vuepress-quickstart.git
$ cd vuepress-quickstart
```
### Install project packages
All the content is in [docs](/docs/), so navigate there.
```sh
$ cd docs
```
Install NPM packages with YRN.
```sh
$ yarn install
```
## Usage
```sh
$ cd docs
```
### Server
Start a dev server.
```sh
$ yarn dev
```
## Deploy
### Build
Build the site to an output directory.
```sh
$ 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](/.github/workflows/docs.yml) workflow.
1. Commit and push your repo.
1. View the _Actions_ tab to check that that build pages.
1. Go to your repo's _Settings_.
1. Enable _GitHub Pages_ - for the project root on the `gh-pages` branch.
1. 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](https://vuepress.vuejs.org/config/) page of the docs. This is setup in [config.js](/docs/src/.vuepress/config.js).
For a _Netlify_ site, you can configure the site the build command and target directory. See my [Configure](https://michaelcurrin.github.io/code-cookbook/recipes/ci-cd/netlify/configure.html) guide.
## Related projects
- [](https://github.com/MichaelCurrin/docsify-js-template)
- 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.
- [](https://github.com/MichaelCurrin/nuxt-default-quickstart)
- Template for a static made with Nuxt, which is built on Vue.
- [](https://github.com/MichaelCurrin/vue-quickstart)
- Template for a Node app using Vue.
## License
Released under [MIT](/LICENSE) by [@MichaelCurrin](https://github.com/MichaelCurrin).