Vuepress Docs

Posted on  by admin
Quick summary ↬One of the most overlooked aspects of creating and/or maintaining any software library is good documentation. Luckily for you, a new tool on the market is here to make it easy for you to create great documentation for your projects.

Documentation is a critical part of a successful project. However, your project may not require a full-fledged documentation system. In these situations, static pages will likely suffice. VuePress parses Markdown files structured in folders into HTML files to be served. VuePress ships with Vue, Vue Router, and webpack. Each Markdown file is parsed as a Vue template and assets are bundled by webpack. Parsing the Markdown files into Vue templates allows you to also utilize native Vue scripts in the form of single-file components.

Step 2 — Creating the Home Page

Note: This tutorial was written with manual installation in mind. An automated scaffolding tool called create-vuepress-site is also available.

  1. In this article, you will build out a static documentation website which is also a single page application using the Vue-powered static site builder, VuePress. If you would like to follow along with this article, you will need:. A local development environment for Node.js. Follow How to Install Node.js and Create a Local Development Environment. This tutorial was verified with Node v16.6.2, npm v8.1.0, and vuepress v1.8.2. In this section, you will create your project and install VuePress. First, create a new project directory:. Next, change into the new project directory:. Then, initialize a new project:. This command quickly scaffolds a new project and creates a package.json file.
  2. Open package.json in your code editor and add the highlighted lines of code:. At this point, you have installed VuePress and modified your package.json to support the dev and build commands. In this section, you will create the directory structure and Markdown files with placeholder text. Take care when creating folders in VuePress, because it evaluates the folders and Markdown files according to their directory structure. Each Markdown file in a folder compiles into an HTML document with the route being the parent folder.
  3. First, create a docs directory to house the components and configuration:. Now, use your code editor to create a new index.md file in this directory:. Special “front matter” syntax (either in YAML, JSON, or TOML format) in the Markdown files instruct VuePress to provide title, lang, and other attributes. At this point, you can build and serve the application and observe what you have so far:. After the application is built, you will be presented with a success message that also provides the URL to visit (by default it should be localhost:8080). Now, open this URL in your web browser. The Markdown code will generate a button for Counter Component, informational columns about features, and a footer.
  4. Now, use your code editor to create a new counter.vue file in the .vuepress/components directory:. This code will display the value (number) and depending on how many times Increment or Decrement buttons are interacted with, that value will change. Now, you will create the page to display the component. Under the docs directory, create a new counter subdirectory:. Now, use your code editor to create a new README.md file in the docs/counter directory:.

Create a couple of additional pages in this directory.

More after jump! Continue reading below ↓

This demonstration will include usage.md:. And see-also.md:. These files will later be transformed into static pages. Now you have all the required Markdown files. In this section, you will configure the site to use a specified title, description, nav, and sidebar.

Jump to table of contents ↬

Conclusion

The config.js file is used to customize the documentation system. Use your code editor to create a new counter.vue file in the .vuepress directory:.

Vue.js + Printing Press

First, you specify the title of the website and assign it a description, which is good for SEO.

This title and description automatically provide an indexed search system on the website with a search bar.

Next in the script is the themeConfig object, which receives parameters required to implement certain functionality on the theme. To create a navbar, you create a nav array that contains objects specifying the display text and route of each nav element.

Step 1 — Setting Up the Project

Note: You can learn more about the navbar in the official documentation. This code also features grouped sidebars so users can have a quick glance at the menu at any time in the documentation.

  • The sidebar menu can be set to collapse by default using the collapsable property on the sidebar group.
  • Note: You can learn more about the sidebar in the official documentation.
  • As a final step to configuring the demonstration, you will override the default colors using styles.

Step 3 — Creating the Counter Page

Under the docs/.vuepress/ directory structure, create a new styles subdirectory:. Now, use your code editor to create a new palette.styl file in the .vuepress/styles directory:. This syntax and file extension is for Stylus sheets. VuePress uses Stylus for configuring colors and breakpoints. Save your changes and restart the development server with the following command:. Note that changes made to the .styl file are reflected in the browser immediately.

You have now completed the documentation system with individual pages. In this tutorial you developed a static documentation website, which is also a single-page app, using VuePress.

VuePress offers the flexibility of writing Vue scripts inside Markdown files which introduces interactive demonstrations. Static sites are considered useful for their speed, security, and maintainability. VuePress is SEO-friendly and by default provides a means to implement analytics tracking using Google Analytics on your pages.

  • Also, VuePress ships with a minimal search system that indexes all headers on the website and displays them upon search.
  • Although VuePress ships with a default responsive layout for documentation, it also supports custom layouts for styling.
  • Continue your learning by modifying the project to include additional folders and corresponding Markdown files.
  • If you would like to learn more about the options available to VuePress, consult our introduction to VuePress.

# Global Installation

Create a VuePress app. Setup an Azure Static Web Apps. Deploy the VuePress app to Azure. An Azure account with an active subscription. If you don't have one, you can create an account for free.

  • A GitHub account. If you don't have one, you can create an account for free. Node.js installed. Create a new folder for the VuePress app.
  • Add a README.md file the folder. Initialize the package.json file. Add VuePress as a devDependency. Open the package.json file in a text editor and add a build command to the scripts section. Create a .gitignore file to exclude the node_modules folder.
  • Initialize a Git repo. Create a blank GitHub repo (don't create a README) from https://github.com/new named vuepress-static-app. Add the GitHub repository as a remote to your local repo. Make sure to add your GitHub username in place of the placeholder in the following command.
  • Push your local repo up to GitHub. Navigate to the Azure portal. Select Create a Resource. Search for Static Web Apps. Select Static Web Apps. On the Basics tab, enter the following values. Select Sign in with GitHub and authenticate with GitHub.

# Inside an Existing Project

Enter the following GitHub values. In the Build Details section, select VuePress from the Build Presets drop-down and keep the default values. Select the Review + Create button to verify the details are all correct.

  1. Select Create to start the creation of the App Service Static Web App and provision a GitHub Actions for deployment. Once the deployment completes click, Go to resource.
  2. On the resource screen, click the URL link to open your deployed application. You may need to wait a minute or two for the GitHub Actions to complete. Open the Azure portal. In the top search bar, search for your application by the name you provided earlier.

Click on the app. Click on the Delete button. Click Yes to confirm the delete action.

If you just want to play around with VuePress, you can install it globally:. If you have an existing project and would like to keep documentation inside the project, you should install VuePress as a local dependency. This setup also allows you to use CI or services like Netlify for automatic deployment on push.

It is currently recommended to use Yarn instead of npm when installing VuePress into an existing project that has webpack 3.x as a dependency.

“What if I want something that will provide lower-level indexing for searching?”

Npm fails to generate the correct dependency tree in this case. Then, add some scripts to package.json:. You can now start writing with:. To generate static assets, run:.

By default the built files will be in .vuepress/dist, which can be configured via the dest field in .vuepress/config.js. The built files can be deployed to any static file server.

Step 4 — Configuring the Layout and Styles

See Deployment Guide for guides on deploying to popular services.

With a simple configuration, VuePress can ensure automatically output the last updated date on the page so your users always know the last time it was updated.

On top of that, with a little bit of configuration, VuePress also makes it incredibly easy for users to contribute to your docs by automatically generating a link at the bottom of every single page that allows users to easily create a pull request to your docs.

It doesn’t get much easier than that for your users.

Prerequisites

Since VuePress is a static site generator at its core, this means that you can deploy it on any popular hosting platform such as:

  • Netlify
  • GitHub Pages
  • GitLab Pages
  • Heroku
  • Now

All you need to do to build the site is run vuepress build {{ docsDir }} with where your directory lives and you’ll have everything you need to deploy it live on the web!

Note: For more in-depth guides on how to do this, check out the official deployment guides for VuePress.

Introduction

I know, I know. We can use Vue.js in our Markdown?! Yes, you read that right! While technically optional, this is probably one of the most exciting aspects of VuePress because it allows you to enhance your Markdown content like you’ve never been able to do before.

Define Repetitive Data In One Place And Have It Update Everywhere With Interpolation

In the example below, you’ll see a brief example of how you can leverage local variables (like the ones define in the frontmatter) as well as globally defined ones (like the site title):

Use Vue Components Within Markdown

I’ll give you a moment to collect yourself after reading this, but yes, live Vue components with a full Vue instance can be yours for the taking if you want! It will take a little bit more work to configure, but this is to be expected since you are creating custom content that will be running in your documentation.

Here is a quick example of what a Counter component would look like in a Markdown file:

This is perhaps the most powerful part of customization available to documentation since it means you now have the freedom to create custom content extends far beyond the abilities of standard Markdown. So whether it’s providing a demo, or some interactive code, the ideas are endless!

Next Steps

If you want to set up a beautiful documentation site for your users to learn how to use your product, it doesn’t get much easier than VuePress. And even though it might be easy to assume that VuePress should only be used by projects that use Vue.js, this could not be further from the truth. Here are just some examples of the different types of projects leveraging VuePress for their documentation sites:

  • UmiJS (which is built for React)

At the end of the day, regardless of whether you use VuePress or not, I hope this has helped to inspire you to create better documentation for your users.

Further Resources

There are many cool things that I did not cover here in this article (e.g. theming, blogging, and so on), but if you would like to learn more, check out these resources:

Explore more on