VuePress is a Vue-powered static site generator that is composed of two parts:
Evan You, the creator of Vue.js, built VuePress to satisfy the documentation needs of various Vue-based projects.
One of the really cool things about VuePress is that it allows you to build a single-page application that has its own pre-rendered static HTML from a Markdown file that is powered by Vue, VueRouter, and Webpack.
There are several reasons to work with VuePress, but the ones that stand out are:
VuePress allows you to write Vue right inside the Markdown file. It’s able to do this because it compiles the Markdown file into HTML and processes them as a template in a Vue component.
VuePress supports some really great extensions that allow you to take writing in Markdown to the next level. For example,
YAML front matter
: set predefined variables or create custom ones in your Markdown file and can be accessed using the$page
variable in any file.Header Anchors
: automatically converts headers into anchor tagsLinks
: automatically convert links in Markdown into VueRouter’s <router-link>
for SPA NavigationEmoji
: write Emojis in MarkdownLine Highlighting in Code Blocks
: highlight a line of code in a Markdown code blockTable of Contents
: tells the processor to pick all the header elements in the Markdown file and render them as a list of items with links. To do this, you would have to write the tag below where you want it to render in the Markdown file
[[toc]]
GitHub-Style Tables
: draw tables in Markdown.VuePress comes with a fully responsive theme that has some little features already embedded such as header-based search, customizable navbar and sidebar, optional homepage, auto-generated GitHub link, and Page edit links.
VuePress makes it easy to customize the default theme as well as create a completely custom theme.
VuePress has an option in the config that allows it to automatically generate and register a service worker that would cache the content for offline use.
VuePress also comes with integrated Google Analytics. To enable it, you have to add your Google Analytics ID in the config.
This one’s kind of self-explanatory, but it feels weird leaving an empty space.
There are two ways in which you can get started with VuePress:
To install globally:
npm install -g vuepress
To add to an existing project:
npm install -D vuepress
Once installation is done, we create our Markdown file, which is going to be the content of the static site and then run the code below to preview it.
vuepress dev
The VuePress setup already has hot reload enabled out of the box, so as you are making changes to your Markdown file, it automatically updates in your browser.
Looking at the preview in the browser, you would notice it’s pretty bald, and almost none of the features mentioned exist yet.
To enable some of these features (homepage, sidebar, navigation, etc.), we need to create a config file.
This file is basically a JavaScript file that allows us to customize/enable or disable features in our project.
For this Javascript file to work it needs to export an object.
To create the file, first you have to create a .vuepress
folder inside your project, then create an empty file inside it and name it config.js
.
To activate the header and search feature we just need to add the title
and description
into the exported object.
module.exports = { title: 'Hello VuePress World', description: 'Just playing around... Skr Skr!' }
The config options are broken down into five sections:
This consists of the least configuration needed to get things up and running, they include:
base
: set the base directory of the sitetitle
: set the title of the sitedescription
: set the content of the meta tag named description
<meta name="description" content="">
head
: add other tags you would like to add in the head section of the HTML page.dest
: set which folder the compiled files will be outputted when you run vuepress build
ga
: specify the ID of your Google Analytics AccountserviceWorker
: specify if you want VuePress to automatically generate and register a service worker that would cache the content for offline useport
: specify the port to run the dev server onmodule.exports = { dest: 'docs', title: 'VuePress', description: 'Just playing around.. Skr! Skr!', head: [ ['link', { rel: 'icon', href: `/logo.png` }], ['link', { rel: 'manifest', href: '/manifest.json' }], ['meta', { name: 'theme-color', content: '#3eaf7c' }], ['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }], ['meta', { name: 'apple-mobile-web-app-status-bar-style', content: 'black' }], ['link', { rel: 'apple-touch-icon', href: `/icons/apple-touch-icon-152x152.png` }], ['link', { rel: 'mask-icon', href: '/icons/safari-pinned-tab.svg', color: '#3eaf7c' }], ['meta', { name: 'msapplication-TileImage', content: '/icons/msapplication-icon-144x144.png' }], ['meta', { name: 'msapplication-TileColor', content: '#000000' }] ], serviceWorker: true, ga: 'UA-109510157-1', port: 8000 }
This consists of all configs relating with the theme to be used in the site.
theme
: pass the name of a custom theme you would prefer to usethemeConfig
: specify all the theme configurations possible for a particular selected themeThis allows you to customize the Markdown extension based on your needs. They include:
markdown.slugify
: Lets VuePress to convert header texts into slugsmarkdown.anchor
: processor will render header tags as linksmarkdown.toc
: decides if the processor should render [[toc]]
or notmarkdown.config
: add additional plugins that are not in the VuePress Markdown systemThis allows you to specify how your production ready file is built. It includes:
postcss
: select options for the PostCSS loaderconfigureWebpack
or chainWebpack
: modify the internal webpack config in VuePressThis provides options that lets the VuePress build to disable some backward compatibility features such as ES5 transpilation, polyfills for IE, etc.
The above can be done with evergreen.
The default theme consists of a homepage which has the following:
The default theme has already created some preset variable in the theme’s YAML front matter that allows us to set the actual data that would be used on the site.
To set these values, you need to create a readme.md
file in the root of your project and specify the correct values in the metadata below:
--- home: true heroImage: /hero.png actionText: Get Started → actionLink: /guide/ features: - title: Simplicity First details: Minimal setup with markdown-centered project structure helps you focus on writing. - title: Vue-Powered details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue. - title: Performant details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded. footer: MIT Licensed | Copyright © 2018-present Evan You --- # Hello VuePress World!
home
: either turn off the homepage view or display itheroImage
: specify the link of the hero image on the homepageactionText
: specify the text on the action button on the homepageactionLink
: allows you to specify what link to navigate to when the action button is clickedFeatures
: specifies content into all the 3 columns of the default themefooter
: allows you to specify the content of the footer of the pageTo enable the navigation links on the header of the page, the default theme provides a themeConfig.nav
option in the config.js
which allows you set the various navigation links.
module.exports = { themeConfig: { nav: [ // Normal Links { text: 'Guide', link: '/guide/' }, { text: 'External', link: 'https://google.com' }, // Links with dropdown { text: 'Languages', items: [ { text: 'Chinese', link: '/language/chinese' }, { text: 'Japanese', link: '/language/japanese' } ] }, // Grouped Items inside dropdown { text: 'Languages', items: [ { text: 'Group1', items: [ { text: 'Chinese', link: '/language/chinese' }, { text: 'Japanese', link: '/language/japanese' } ] }, ] } ] } }
To enable the sidebar layout, the default theme provides a themeConfig.sidebar
option, that allows us to specify the various links in the sidebar.
The sidebar also has a grouping feature of links which you can specify if you want it collapsible or not.
For a sidebar item to be visible, the file being referenced has to exist.
--- home: true heroImage: /hero.png actionText: Get Started → actionLink: /guide/ features: - title: Simplicity First details: Minimal setup with markdown-centered project structure helps you focus on writing. - title: Vue-Powered details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue. - title: Performant details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded. footer: MIT Licensed | Copyright © 2018-present Evan You --- # Hello VuePress World!
NOTE: Sidebar only works in Markdown files that don’t have the home
option set to true
.
The default theme stylesheet was built with a preprocessor called stylus which allows us to define variables in stylesheets.
This makes it easy for us to change a few preset colors and the styles get applied across.
To override some of the styles you have to create an override.styl
file in the .vuepress
folder and specify the value changes.
List of variables you can currently override:
// colors $accentColor = #3eaf7c $textColor = #2c3e50 $borderColor = #eaecef $codeBgColor = #282c34 $arrowBgColor = #ccc // layout $navbarHeight = 3.6rem $sidebarWidth = 20rem $contentWidth = 740px // responsive breakpoints $MQNarrow = 959px $MQMobile = 719px $MQMobileNarrow = 419px
Deploying a VuePress site is pretty easy, depending on the platform of your choice.
First, we have to make a production-ready site.
To do this we change the directory of our terminal to the root of our project and then run the code below
vuepress build
This compiles our Markdown into Vue components which in turn is processed by the VuePress build setup to generate a fully pre-rendered single page application that is both fast and SEO-friendly in the .vuepress/dist
directory unless stated otherwise in the config.js
file.
Now you can deploy your production ready site, the way you would deploy any other static website.
Found this article helpful? Don’t forget to clap and share 🙂
Debugging Vue.js applications can be difficult, especially when there are dozens, if not hundreds of mutations during a user session. If you’re interested in monitoring and tracking Vue mutations for all of your users in production, try LogRocket.
LogRocket is like a DVR for web and mobile apps, recording literally everything that happens in your Vue apps, including network requests, JavaScript errors, performance problems, and much more. Instead of guessing why problems happen, you can aggregate and report on what state your application was in when an issue occurred.
The LogRocket Vuex plugin logs Vuex mutations to the LogRocket console, giving you context around what led to an error and what state the application was in when an issue occurred.
Modernize how you debug your Vue apps — start monitoring for free.
Hey there, want to help make our blog better?
Join LogRocket’s Content Advisory Board. You’ll help inform the type of content we create and get access to exclusive meetups, social accreditation, and swag.
Sign up nowSOLID principles help us keep code flexible. In this article, we’ll examine all of those principles and their implementation using JavaScript.
JavaScript’s Date API has many limitations. Explore alternative libraries like Moment.js, date-fns, and the new Temporal API.
Explore use cases for using npm vs. npx such as long-term dependency management or temporary tasks and running packages on the fly.
Validating and auditing AI-generated code reduces code errors and ensures that code is compliant.