VuePress is a Vue-powered static site generator that is composed of two parts:
- A theming system
- A default theme optimized for writing technical documentation
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.
Why VuePress?
There are several reasons to work with VuePress, but the ones that stand out are:
1. Vue inside MarkdownĀ files
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.
2. Built-in Markdown extensions
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.
3. DefaultĀ theme
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.
4. CustomĀ theme
VuePress makes it easy to customize the default theme as well as create a completely custom theme.
5. ServiceĀ workers
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.
6. Google Analytics
VuePress also comes with integrated Google Analytics. To enable it, you have to add your Google Analytics ID in the config.
7. Multilanguage support
This oneās kind of self-explanatory, but it feels weird leaving an empty space.
Getting started
There are two ways in which you can get started with VuePress:
- Installing it globally
- Adding it to an existing project
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.
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:
1. BasicĀ config
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 runvuepress 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 on
module.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 }
2. ThemingĀ config
This consists of all configs relating with the theme to be used in the site.
More great articles from LogRocket:
- Don't miss a moment with The Replay, a curated newsletter from LogRocket
- Learn how LogRocket's Galileo cuts through the noise to proactively resolve issues in your app
- Use React's useEffect to optimize your application's performance
- Switch between multiple versions of Node
- Discover how to animate your React app with AnimXYZ
- Explore Tauri, a new framework for building binaries
- Advisory boards arenāt just for executives. 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.
theme
: pass the name of a custom theme you would prefer to usethemeConfig
: specify all the theme configurations possible for a particular selected theme
3. MarkdownĀ config
This 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 system
4. BuildĀ config
This allows you to specify how your production ready file is built. It includes:
postcss
: select options for the PostCSS loaderconfigureWebpack
orchainWebpack
: modify the internal webpack config in VuePress
5. Browser Compatibility config
This 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.
Coupling the default theme partsĀ together
The default theme consists of a homepage which has the following:
- Hero image
- Action button
- A section composed of three columns, each with a title and caption
- A footer
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!
Explaining the codeĀ above
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 page
Navbar Links
To 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' } ] }, ] } ] } }
Sidebar layouts
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
.
Switching colors
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
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Ā š
Experience your Vue apps exactly how a user does
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.