Create a Documentation and Blog site using VuePress (r) (r)

-sidebar-toc>

What Is VuePress?

What are the benefits of using VuePress?

These are the convincing reasons to consider why VuePress might be the perfect selection for you.

1. Markdown ease of use: VuePress simplifies content creation with Markdown which makes it simple to create and organize the content you want to publish without requiring complicated formatting.
2. Vue.js integration: VuePress seamlessly integrates Vue.js to provide interactive and dynamic web elements that provide an enjoyable user experience.
3. Performance and customization: VuePress offers excellent performance, with speedy loading static websites as well as a variety of customization options that match your style and needs.

Beginning On VuePress

In this post, we'll make use of the manual installation technique.

1. Create a new directory and change it:

mkdir vuepress-starter && cd vuepress-starter

1. Initiate using your preferred package manager. For this article, let's utilize Yarn.

yarn in it

1. Install VuePress in your project as a dependent for developers:

yarn add -D vuepress

1. Create a document folder that will house the entirety of your code. Then you can create the README.md file, which serves as the index file for your project similar to index.html:

mkdir docs && echo '# Hello VuePress' > docs/README.md

1. Open your project in an editor for code and then add the following scripts to your package.json file so you are able to serve and develop your website:

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

It is now possible to connect to your website by using your yarn dev command. VuePress will start your development server at http://localhost:8080.

It is now time to create your own documentation site. You'll notice that VuePress has a sleek, minimalist default theme straight out of the box. However, it's highly customizable, giving users the ability to create a distinctive style and look for your site.

Creating Pages for Documentation

You can, for instance, create files like getting-started.md, usage.md, and troubleshooting.md. These files automatically become routes that can be accessed when you navigate to http://localhost:8080/getting-started, http://localhost:8080/usage and http://localhost:8080/troubleshooting.

To enhance the organization of your documentation to make it easier for you to organize your documentation, you can design separate folders that contain related documentation pages. In this case, you could create a folder named "guide," and arrange it according to particular guides, such as using--stsh.md. When you employ this structure, the content in using--stsh.md becomes accessible via a URL like http://localhost:8080/guide/using--stsh.

Additionally, you can make a README.md or index.md file at the top in the guide directory. This file will serve as the index page, allowing users to navigate to http://localhost:8080/guide/ and conveniently access the content with a sidebar you will learn how to configure in the next section.

Within this VuePress sample repository, you will notice that the files have been constructed, with certain markdown-related content was added to each document. You are free to design your files to your preferences, by starting from scratch and adjusting them to your needs, or taking inspiration from the material that is available in the repository.

Modifying VuePress Appearance

When you've finished filling the documentation website with all of your contents, you could find it challenging to navigate particularly if you've got many files to manage. But, VuePress allows you to alter the layout of your site, making it more user-friendly and organized.

For customizing your website's look and navigation, you need to create a .vuepress folder in the root directory of your site. This folder will hold the configuration files as well as assets that are related to your VuePress site.

Navigation Configuration

Within the .vuepress folder, create in the.vuepress folder, a config.js file. It is also possible to use different formats for files like YAML (.yml), TOML (.toml) and TypeScript (.ts) for your configuration.

In your config.js file, you'll be able to define the navigation structure of your site by using the themeConfig object. This is an example of a configuration:

module.exports = 
 title: ' Vuepress',
 description: 'A VuePress QuickStart for ',
 themeConfig: 
 nav: [
 
 text: 'Guide',
 link: '/guide/',
 ,
 
 text: 'Static Site Hosting',
 link: 'https://.com/static-site-hosting/',
 ,
 ],
 sidebar: 
 '/guide/': [
 
 title: 'Guide',
 collapsable: false,
 children: ['', 'using--stsh'],
 ,
 ],
 ,
 ,
 ;

In this case we'll be configuring the website's title as well as description as well as defining links for navigation, and setting up as a sidebar in the /guide/ section.

The NAV array specifies navigation hyperlinks that are located at the very top of your website. The sidebar object defines the sidebar structure for specific sections. For this example it's configured to the section /guide/. section.

Learn more about how to configure navbars within the VuePress documentation.

Styling

VuePress allows you to customize the appearance of your site by using designs. You are able to either alter the default stylings using specified variables or establish your design. To accomplish either of these, make a the styles folder within the .vuepress folder

To make simple changes to the styling of the default preset or define some variables to use at a later time, create a palette.styl file in .vuepress/styles. There are some variables that have been predefined you can tweak:

// colors
 $accentColor = #5333ED
 $textColor = #2c3e50
 $borderColor = #eaecef
 $codeBgColor = #282c34
 $arrowBgColor = #ccc
 $badgeTipColor = #42b983
 $badgeWarningColor = darken(#ffe564, 35%)
 $badgeErrorColor = #DA5961
 
 // layout
 $navbarHeight = 3.6rem
 $sidebarWidth = 20rem
 $contentWidth = 740px
 $homePageWidth = 960px
 
 // responsive breakpoints
 $MQNarrow = 959px
 $MQMobile = 719px
 $MQMobileNarrow = 419px

.content 
 font-size 30px
 

Learn more about styling VuePress in the documentation for VuePress.

Using Components

VuePress allows the use of components that can enhance the function and appearance of your pages. It is possible to create Vue components and add them in your Markdown files. Create an

components folder in .vuepres, and the *.vue files found in .vuepress/components are automatically recognized to be global components.

Consider, for instance, creating two elements, HomeOptions.vue and HostingBanner.vue:

. +- .vuepress
+- component
+- HomeOptions.vue
+- HostingBanner.vue

Within these vue.js component files You can also add CSS codes. We'll add codes to the HomeOptions.vue and HostingBanner.vue components.

Incorporate the following code into HomeOptions.vue:

 
 
 
 a 
 color: #2c3e50;
 
Hover color: #5333ed.options Display: flex; width: 10px; Margin: 40px.option Border: 2px solid #eaecef; padding: 10px. 

Also, add the below code HostingBanner.vue:

  
 Host Your Static Site For Free!
 Read More/a>

 scoped>.banner 
 background: rgb(156, 85, 34);
 background: linear-gradient(
 90deg,
 rgba(156, 85, 34, 1) 0%,
 rgba(32, 50, 103, 1) 42%,
 rgba(13, 18, 25, 1) 69%,
 rgba(22, 47, 60, 1) 100%
 );
 color: #fff;
 padding: 20px;
 border-radius: 5px;
 display: flex;
 justify-content: center;
 align-items: center;
 flex-direction: column;
 
the.banner p.banner p 
 width: 600px;
 font-size: 40px;
 font-weight: bold;
 text-align: center;
 line-height: 50px;
 .banner .btn the border is 5px wide; the margin bottom is 10px high.banner .btn:hover the background to #111319, color #ffff. 

In any Markdown file, you may then directly use the components (names are inferred from name of the file):

Read more about features in VuePress in the help documentation.

Personalize the homepage

In VuePress The default theme comes with a designed homepage layout you can utilize to build an attractive and useful starting page for your website. In order to use the homepage design it is necessary to set home as true and add some extra information within the YAML frontmatter in your base README.md file.

Here's an example of YAML frontmatter:

---
home: trueheroImage: /hero.png
 heroText Tagline for Hero Title: Hero subtitle
 actionText"Get Started"actionLink Guide/features titles simple First description: Minimal setup with markdown-centered structures helps you concentrate on your writing. - title: Vue-Poweredinformation: Experience the developer experience of Vue with webpack. Use Vue elements in markdown and build custom themes with Vue. - title: Performantspecifics: VuePress generates pre-rendered static HTML for every page and runs as an SPA once a page is loaded. footer MIT Licensed Copyright (c) 2018-present Evan You
Evan You---

The configurations above can make your homepage for documentation appear like:

You can turn off the heroText and tagline as well as any other information by setting the fields that they correspond to in the field to null If you'd prefer a more simple layout, or not including the information. Anything you add within the YAML frontmatter (i.e. the metadata section) will be considered normal Markdown, and rendered following the features section.

If you want a fully personalized homepage layout, VuePress also supports Custom Layouts. You can also create rich-text footers using Markdown Slot Syntax, offering more flexibility in displaying the content of your footer. Here's an example of how to make a rich-text footer:

---
home: true--
: Footer of the slotMade with by . [Static Site Hosting](https://.com/static-site-hosting/)
 :::

If this is the case the contents of the Footer of the slot section allows you to include links and additional information in the footer area on your home page.

After you have a better understanding of how to perform the above adjustments, simply add the components added earlier to the Homepage and then remove the options so the Homepage is more appealing:

"code> >---
home: True
 tagline: A VuePress QuickStart with ActionText: Quick Start
 actionLink Guide/--
- 

: Footer of the slotCreated with . [Static Site Hosting](https://.com/static-site-hosting/)
 :::

When you apply these VuePress customizing techniques by following these VuePress customization techniques, you can build an informative website that is not just a source of important content, but also the best user experience, with well-organized navigation and attractive styling.

There is more information on changing the default theme within the help file.

The creation of a blog section using VuePress

Adding a blog section to your VuePress website is easy as VuePress allows you to create custom Vue components that are inserted into any Markdown documents. Let's create a component which renders the post's list.

Create an BlogIndex.vue file in the components folder. Add the following code:

 
 >
 export default 
 computed: 
 posts() 
 return this.$site.pages
 .filter(
 (x) => x.path.startsWith('/blog/') && !x.frontmatter.blog_index
 )
 .sort(
 (a, b) =>
 new Date(b.frontmatter.date) - new Date(a.frontmatter.date)
 );
 ,
 ,
 ;
 

In the provided code snippet in the code snippet, you can design a Vue template which runs through your blog's posts by using the v-for and displays the post's title, description, and also a "Read more" link for each post.

The script section exports the Vue component which computes and reads blog entries. These posts are filtered according to their location (starting with the letter /blog/) and also the absence of blog_index frontmatter. blog_index frontmatter attribute. They are then sorted by the date, in order of descending to show the most recent ones first.

If you're creating new blog posts, it is necessary include the date of your post as part of the frontmatter information. This will help sort the posts so that the newest post appears first.

To save blog entries Create a folder called blog in the root folder of your project. Within this folder, you can add a README.md file. This is going to be the blog index which is the place to incorporate your BlogIndex element to display every blog post.

blog_index: trueblog_index: true
--- Blog
Welcome to Our Blog

Make sure to include the blog_index frontmatter property, since it is instrumental in ensuring that the blog index itself isn't listed in individual blog posts. This attribute is used for filtering posts within the property that computes posts that is part of BlogIndex.vue. BlogIndex.vue component.

Create an archive folder for blogs at the root of your project to store blog posts and create each post. In this case, for example, create a first-post.md file and insert the following markdown information:

A code >---
name: "My Exciting VuePress Blog Journey"
 Date: 2023-9-28 September, 28description: "Exploring VuePress, a flexible static website generator, and sharing my experience throughout the process." ---# My exciting VuePress Blog Journey
In this first blog post I begin an adventure with VuePress an extremely powerful static site generator ideal for the creation of blog posts, documentation, and more. When I dive into the realm of VuePress, I'll be sharing my insights, experiences as well as tips for getting the most from this fantastic tool.

For each blog post, be sure to define the necessary aspects of the frontmatter, like the title of your post, its date, and other relevant metadata. A meticulously organized blog ensures that your blog content is organized well and provide a captivating reader experience to your readers.

In the end, you are able to add the blog navigation to your navbar in the .vuepress/config.js file:

nav: [
 
 text: 'Guide',
 link: '/guide/',
 ,
  text: 'Blog', link: '/blog/' ,
 
 text: 'Static Site Hosting',
 link: 'https://.com/static-site-hosting/',
 ,
 ],

There is a lot you can do by using VuePress for example, including plugins, using a distinct theme as well as designing your own theme.

Deploy VuePress Static Site To

# dependencies
 /node_modules
 
 # build directory
 ./docs/.vuepress/dist
 /public

1. Log in or create an account to see your My dashboard.
2. Authorize with your Git provider.
3. Go to Static Sites in the sidebar left Click Static Sites, and select Add Site. Add Site.
4. Choose the repository as well as the branch you would like to use for deployment.
5. Assign a unique name to your site.
6. Set the build parameters using the format below:

• Build command: NPM run build
• Node version: 16.20.0
• Publish directory: ./docs/.vuepress/dist or public

1. Finally, click to create your site..

Summary

VuePress is a versatile and powerful tool for creating rapid blog websites and documentation. With its simple setup as well as customizable themes and plugins, you can develop a highly informative and visually appealing platform that will appeal to your readers.

Create your VuePress site today and share your knowledge all over the world. You can host your VuePress site your site on our Static Site Hosting for free!

   Have you ever used VuePress for building anything? Please share your projects and experiences to us via the comment section below.

Joel Olawanle

Joel is an Frontend Developer working as Technical Editor. He is a passionate educator who is a lover of open source and has written over 200 technical papers, mostly on JavaScript and its frameworks.

•                 Website                                          
•                 LinkedIn                                          
•                 Twitter