VuePress Tutorial For Beginners

0
37
VuePress Tutorial For Beginners

VuePress comprises two parts: a minimalistic static site generator with a Vue-powered theming system and a default theme optimized for writing technical documentation.

Each page generated by VuePress has its own pre-rendered static HTML, providing excellent loading performance and is entirely SEO-friendly.

Once a page is loaded, Vue takes over the static content and turns it into the complete Single-Page Application (SPA). Additional pages are fetched on demand as the user navigates around the site.

VuePress Features

  • Built-in markdown extensions optimized for technical documentation.
  • Ability to leverage Vue inside markdown files.
  • Vue-powered custom theme system.
  • PWA Support.
  • Google Analytics Integration.
  • A default theme has:
    • Responsive layout.
    • Optional Homepage.
    • Simple out-of-the-box header-based search.
    • Customizable navbar and sidebar.
    • Auto-generated GitHub link and page edit links.

VuePress Tutorial

First, we will install the VuePress on our local machine. So let us do it.

Step 1: Install VuePress.

Create a project directory called vpress.

mkdir vpress

Go into that directory.

cd vpress

I am using Yarn as a package manager, so let us pull the package using the following command.

yarn add vuepress

If you are not using Yarn, then you can pull through NPM.

npm install vuepress --save

Now, open the project in your favorite editor.

code .

Step 2: Create a folder inside the root.

Inside the project root folder, create one folder called docs.

Now, in that folder, make one markdown file called README.md.

If you have previously written the Github Documentation, then you are familiar with Markdown Files. Also, you are familiar with the README.md file.

In the README.md file, write the following line of code.

# Hello World

Okay, now we need to run the project.

Step 3: Run the Project in the development server.

Go into your root folder, open the terminal, and hit the following command.

npx vuepress dev docs

VuePress Example Tutorial

Switch to your browser and go to this URL: http://localhost:8080/

You can see the Hello World. Here # means h1 tag equivalent to HTML. It is simple Markdown syntax.

You can add the scripts to the package.json file.

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

Stop the server by control + c and then start the server with the following command.

npm run docs:dev

You can also generate the static assets using the following command.

npm run docs:build

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

Step 4: Configuration.

For creating a configuration file, we need to create a folder inside the docs folder called .vuepress.

Inside the .vuepress folder, create a  javascript file called config.js file.

// config.js

module.exports = {
  title: 'First VuePress Project',
  description: 'Exploring VuePress'
}

Okay, if your development server is running, you can see that the page now has a header with the title and a search box. This is because VuePress comes with built-in headers-based search – it automatically builds a simple search index from the title, h2, and h3 headers from all the pages.

VuePress

You can apply more configurations, for example, base, title, head, Google Analytics, Port number, etc.

Step 5: Asset Handling

In our project, the docs folder is mainly reacting as a root folder, so we need to create one folder called images inside the docs folder and then move any local image to that folder. We can access using this syntax.

README.md

# Hello world

![An image](./images/Krunal.jpg)

We can see the image on our page. You can check out more options here.

Step 6: Create a second md file inside the docs folder.

Create a second Markdown file inside the docs folder called Demo.md. Write the following line inside that file and save it.

# This is second demo

Now, see the project in the browser.

VuePress Markdown Tutorial

You can see here that the content is displaying in the browser, and after clicking that link, we can redirect to a new route, which is Demo.html. 

We have not defined any route, but still, VuePress takes that second file as another route, and after clicking that link, we redirect to that page. How cool is that!! It automatically figures it out by itself.

You can check out the markdown extensions. It is handy for creating content.

In the future, we will build an entirely static website with the help of VuePress.

Conclusion

It is the perfect framework for creating technical documentation and blog. It is server-side rendered, so entirely SEO-friendly. VuePress Tutorial For Beginners is over.

Leave A Reply

Please enter your comment!
Please enter your name here

This site uses Akismet to reduce spam. Learn how your comment data is processed.