Skip to content
This repository has been archived by the owner on Mar 23, 2021. It is now read-only.

Home

Jump to bottom
Sander Moolin edited this page Apr 2, 2018 · 7 revisions

Vuepress is a boilerplate template used to build fast, responsive Vue.js sites with the reliability and wide support of WordPress. It’s built and maintained by Funkhaus.

This tutorial is a work in progress! Please feel free to raise issues or reach out to the team for more information.

Prerequisites

You should have at least some familiarity with the following before working with Vuepress:

  • Node & NPM
  • Vue.js
  • WordPress

Vuepress also uses Vuex and the Vue Router, but it isn’t necessary to know them before getting started (it certainly doesn’t hurt, though!).

WordPress setup

We’re not going to cover setting up WordPress in this tutorial, but you should have your own WordPress development environment running locally to work in Vuepress.

The Vuepress team has had the best luck with Local by Flywheel, a desktop app that greatly simplifies spinning up and managing local WordPress instances. It’s free to use and integrates very well with the Flywheel hosting service, though it doesn’t require using that service.

If you’re interested in getting things running by hand, you could try XAMPP or search for another method to set up local WordPress installations.

Installing Vuepress

We’re assuming that by this point you can:

  1. Start up a local WordPress development environment
  2. Access your wp-content/themes folder
  3. Log in to your WordPress admin account.

If you’re not sure about any of those, we highly recommend taking a look at some tutorials and returning when you’re ready.

Downloading [advanced] If you’re comfortable with git and Github, you can clone the basic branch of https://github.com/funkhaus/vuepress to your wp-content/themes folder and skip ahead to “Plugins.” [/advanced]

Vuepress is available here as a .zip file - go ahead and download that first.

[advanced] We’re linking to the basic branch of the Vuepress repo, which has only the structure necessary to get Vuepress up and running. The master branch is much more fully-featured, but contains a few in-house conventions for Funkhaus, the company behind Vuepress. The basic branch is a great place to start if you’re interested in learning the basics or have your own setup in mind. [/advanced]

When it’s ready, unzip into your wp-content/themes folder:

Then head to http://your-site.local/wp-admin/themes.php in your web browser (we’ll be omitting the http://your-site.local from here on) and activate the new theme:

When your theme is activated, Vuepress will prompt you to install a new plugin:

Click on “Begin Installing Plugin” to continue.

Plugins

This notification is Vuepress’s way of prompting you to automatically download and install Rest-Easy (also built by Funkhaus).

[core-concept] Rest-Easy is necessary for Vuepress to work. It converts WordPress data - posts, menus, media, etc. - into JSON data, which Vue uses to build its front-end. It’s not necessary to understand everything about how it works to use it, but it’s helpful to know that Rest-Easy is the link between the two halves of Vuepress, Vue and WordPress. [/core-concept]

[advanced] Why not just use the WordPress REST API? ****A few reasons:

  • Rest-Easy responses are more customizable and compact than WP REST API responses are, and come with a lot of standard information (like related posts, featured images, etc) built in.
  • Rest-Easy also helps keep frontend JS completely separate from server logic - you’ll just about never need to worry about post IDs in Vuepress, for example.
  • Rest-Easy will end up making fewer requests in most cases than the WordPress REST API, easing load times and improving user experience.

[/advanced]

Advance through the installation of Rest-Easy by installing and activating the plugin.

Next, let’s set up a front page so we can welcome our users.

The Front Page [advanced] If you already know how to (a) set up a front page and (b) change permalinks to just use the post name in WordPress, do so and skip to the next section. [/advanced]

Head to /wp-admin/options-reading.php to select your own front page:

Select the premade “Sample Page” for your Homepage, then click “Save Changes.”

Finally, let’s make sure the rest of the page links will work correctly.

Permalinks

Head to wp-admin/options-permalink.php and set your permalinks to “Custom Structure,” then click the %post_id% and %postname% tags:

Save this new structure to set up our permalinks to use the name of the post or page, which is necessary to use the Vue router.

That’s it for the back-end! Let’s continue to the front-end.

Clone this wiki locally