Create a Documentation and Blog website using VuePress (r) (r)
-sidebar-toc>
What is VuePress?
What are the advantages of utilizing VuePress?
These are some convincing reasons to consider why VuePress might be the perfect selection for you.
- Markdown's user-friendliness: VuePress simplifies content production using Markdown, which makes it simple to create and manage the content that you would like to share without the need for complex formatting.
- Vue.js integration VuePress effortlessly integrates Vue.js to provide an interactive and dynamic web element that offer a pleasurable user experience.
- Efficiency and customisation: VuePress offers excellent efficiency, speedy loading static websites as well as a variety of customization options that match your preferences and style.
Beginning On VuePress
In this post we'll use the method of manual installation.
- Create a new directory. alter it to:
mkdir vuepress-starter && cd vuepress-starter
- Start by logging into your preferred package administrator. In this case, we'll use Yarn.
yarn inside it
- Install VuePress in your project as a dependency for developers
yarn add -D vuepress
- Make a document folder that will house the entire software. Then you can build your README.md file, that serves as an index file of your program as similar to index.html:
mkdir docs && echo '# Hello VuePress' > docs/README.md
- Start your website in an editor that supports code, then include the following scripts into the package.json file so you are able to serve and build your site:
"scripts": "dev": "vuepress dev docs", "build": "vuepress build docs" ,
It is now possible to connect to your website by using your yarn development
command. VuePress will start your development server at http://localhost:8080.
Now is the time to build your own site for documentation. It will be apparent that VuePress offers a modern minimalist theme right out of the box. It's also highly customizable and gives users the option of designing distinct style and design to your website.
Creating Pages for Documentation
For instance, you can you can create files such as 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.
In order to improve the organization of your documentation and help you to organize your documentation, you can design separate folders that contain related documentation pages. In this instance it is possible to make a folder titled "guide," and organize it in accordance with 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.
You can also create a README.md or index.md file at the highest point of the guides 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 example repository It is evident that the documents have been constructed, with certain marking-related information added to each document. You are free to design your own files according to your personal preferences beginning from scratch and altering them according to your requirements and/or drawing an inspiration from the materials that is available on the repository.
Modifying VuePress Appearance
When you've finished filling the website for documentation with all of your contents It can be difficult to navigate, especially if you've got many files to handle. But, VuePress allows you to change the layout of your site, making your site more user-friendly and well-organized.
To customize your site's appearance and layout, you'll need to set up the .vuepress folder in the root directory of your site. The folder contains the configuration files as well as assets that are related to your VuePress website.
Navigation Configuration
Within within the .vuepress folder, create in the.vuepress folder in the.vuepress folder, a config.js file. You can also use different formats for files such as YAML (.yml), TOML (.toml) and TypeScript (.ts) for your settings.
In the config.js file, you'll be able to define the layout of navigation on your website by making use of the themeConfig
object. Here's an example of a setting:
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 set up the website's title
as well as description
and creating links for navigation and setting it up an additional sidebar within the /guide/
section.
This "NAV"
array specifies navigation hyperlinks found at the very top of your web page. The sidebar object specifies the structure of your sidebar for certain sections. In this case, it's set for the section called /guideguide.
section.
Learn more about how to configure the navbars inside the VuePress document.
Styling
VuePress allows you to customize the design of your website by using designs. You are able to either alter the default stylings by using specific variables, or create your own design. To accomplish either of these you need to create your styles folder within the .vuepress folder
To make simple changes to the style of the default preset, or define some variables to use in the future you can create the palette.styl file in .vuepress/styles. There are a few variables which have been defined that to be tweaked:
// colors $accentColor = #5333ED $textColor = $2c3e50. $borderColor = #eaecef. $codeBgColor = #282c34 $arrowBgColor = #ccc $badgeTipColor = #42b983 $badgeWarningColor = darken(#ffe564 3,5 percent) $badgeErrorColor = #DA5961 // layout $navbarHeight = 3.6rem $sidebarWidth = 20rem $contentWidth is 740px. The home page width is 960px. The responsive breakpoints are $MQNarrow = 959px $MQMobile = 719px $MQMobileNarrow = 419px
.content font-size 30px
Learn more about how to style VuePress by reading the manual for VuePress.
Using Components
VuePress permits the use of components that can improve the functionality and look of your websites. You can create Vue components and then include them to your Markdown files. Create the components
components folder in .vuepres, and the *.vue
files found in .vuepress/components are automatically acknowledged as global components.
For instance, think about the creation of two elements: HomeOptions.vue and HostingBanner.vue:
. +- .vuepress +- component +- HomeOptions.vue +HostingBanner.vue HostingBanner.vue
Within these vue.js component files You can also add CSS codes. We'll add codes to these components. HomeOptions.vue and HostingBanner.vue components.
Incorporate the following code into HomeOptions.vue:
A color code: #2c3e50. hover color is #5333ed.options display: Flex size: 10px width; margin: 40px.option The border is 2 pixels solid #eaecef; padding: 10px.
Also, add the below number of characters HostingBanner.vue:
Create a static website for No Cost! Learn More/a> scoped>.banner Background: rgb(156, 85, 34); background: linear-gradient( 90deg rgba(156 85, 34, 1) zero, rgba(32, 50, 1,) 42%, rgba(13 18, 25, 1) 69 percent, rgba(22, 47, 60,) 100 percent ); color: #fff; padding 20px; border-radius: 5px; display: flex and justify-content. Center align-items: central and flex-direction column. the.banner p.banner p width: 600px; font size: 40px font-weight: bold alignment of text: center; line height 50px .banner .btn the border is 5px wide; the margin at the bottom is 10 pixels high.banner .btn:hover over the background to #111319, color #ffff.
If you have a Markdown file, you are able to immediately use the elements (names are inferred from the name of the document):
Find out more information about the features of VuePress in the help documentation.
You can personalize the homepage
Within VuePress The default theme includes the layout of your homepage that you can utilize to build an attractive and effective homepage for your site. For you to utilize the layout for your homepage it's necessary to set home as true
and add some extra details in the front matter of YAML in your basic README.md file.
Here's an example YAML frontmatter:
Code >--- home image: /hero.png heroText Tagline for Hero Title: Hero subtitle actionText"Get Started"actionLink The guide/features title is simple: Minimal setup with Markdown-centered structures allows you to focus on the writing. - title: Vue-Poweredinformation: Experience the developer experience of Vue with webpack. Use Vue elements with markdown to develop custom themes using Vue. Title: Performantspecifics: VuePress produces static HTML that is pre-rendered for each page, and then runs as an SPA after a webpage is loaded. footer MIT Licensed Copyright (c) 2018-present Evan You Evan You---
These configurations can create your documentation homepage to look something similar to:
You may disable any heroText
and tagline
and any other data by setting the fields are associated with that field. zero.
If you'd rather an easier layout or omitting the info. Any information you insert in the YAML frontmatter (i.e. that metadata part) will be considered normal Markdown, which will then be rendered in accordance with the features section.
If you're looking for a completely personalized homepage layout, VuePress also supports Custom Layouts. You can also create rich-text footers using Markdown Slot Syntax. It gives greater flexibility when it comes to display of the contents in your footer. Here's an example of how to make an elegant footer using rich text:
• Code >--- home"true" : The footer of the slotMade is created by . [Static Site Hosting](https://.com/static-site-hosting/) :::
If this is the case the contents of the section Footer
section will allow you to incorporate links and other details in the footer section of your home page.
Once you've a clear understanding of how to perform these adjustments, you can include the elements you added previously to the Homepage and then eliminate the choices so that your Homepage is more appealing:
"code>> >---"code>" home True tagline: VuePress QuickStart with ActionText: Quick Start ActionLink Guide/- Footer of the slots created using . [Static Site Hosting](https://.com/static-site-hosting/) :::
If you implement these customizing methods for VuePress by following these VuePress customization techniques and you will be able to build an impressive website that's not just an excellent source for essential content, but provides an enjoyable user experience featuring well-organized navigation, and appealing design.
More information about changing your default themes in the Help file.
The design of a blog using VuePress
Adding a blog section to your VuePress website is simple because VuePress lets you create custom Vue components to be added inside every Markdown documents. Let's make a part that renders the blog's 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 an Vue template that runs the blog's content making use of the v-for
and displays the title of your post, its description as well as a "Read more" hyperlink for every post.
The script section exports the Vue component that computes and reads blog post entries. They are classified by their place of origin (starting by the letter"/blog/"
) and also there is no blog_index frontmatter. blog_index
frontmatter attribute. Then they're sorted by the date, in the order that descends to show the most recent ones first.
If you're creating new blog posts, it is essential to include the date you published your blog post as part of the information for front matter. This can help you sort your posts so that the newest blog post is the first to appear.
For saving blog entries, create the folder blog within the root folder of the project. In the folder, you will be able to add the README.md file. This is going to be your blog index, which will be the location to add 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 as it's essential to ensure that the index of your blog isn't included in the individual blog posts. This attribute is used for filtering posts within the property used to calculate posts that is part of BlogIndex.vue. BlogIndex.vue component.
Make an archive folder for blogs at the root of your plan to keep blog entries and then create every blog post. For instance, make the first-post.md file and include the following information in markdown format:
A code >--- code with the name "My exciting VuePress Blog Journey" The date is 2023-9-28 September 28description "Exploring VuePress, a flexible static site generator and sharing my experience throughout the process." ---# My exciting VuePress Blog Journey debut blog post, I am beginning my journey with VuePress an incredibly powerful static site generator perfect for creating blog posts, documentation, and much more. In my journey into VuePress's complexities, I'll be sharing my thoughts, experiences and tips on making the most of this fantastic tool.
For each blog post, make sure you have defined important aspects of the headline, such as the title of your post along with the date it was published as well as other pertinent metadata. A meticulously organized blog ensures that your blog content is efficiently organized, and will provide a captivating reader experience to the readers.
Then it is possible to integrate the blog's navigation into your navigation bar in your .vuepress/config.js file:
nav: [ text: 'Guide', link: '/guide/', , text: 'Blog', link: '/blog/' , text: 'Static Site Hosting', link: 'https://.com/static-site-hosting/', , ],
You can do a lot with VuePress. can achieve using VuePress such as adding the plugins, using a unique theme in addition to making your own themes.
Deploy VuePress Static Site
# dependencies /node_modules # build directory ./docs/.vuepress/dist /public
- Sign in or create an account to access Your dashboard. My dashboard.
- Authorize with your Git provider.
- Click on Static Sites in the left-hand sidebar. Select Static Sites, and select Add Site. Create Site.
- Choose the repository and branch you would like to deploy from.
- Assign a unique name to your site.
- Create the parameters for your build by following the template below:
- Build command:
NPM run build
- Node version:
16.20.0
- Publish directory:
./docs/.vuepress/dist
orpublic
- Finally, click to make your website..
Summary
VuePress is an incredibly versatile and powerful tool for creating quick blog sites and documentation. With its simple setup and customizing themes and plugins you can develop a highly engaging and attractive platform that is appealing to readers.
Create your VuePress website today and start sharing your expertise with the globe. You can host your VuePress website with our Static Site Hosting for free!
Have you ever used VuePress to create something? Please share your projects and your experiences with us in the comment section below.
Joel Olawanle
Joel is a Frontend Developer working as Technical Editor. He is an avid educator who is a lover of open source and has published more than 200 technical papers, most of them on JavaScript and the frameworks it uses.
Article was first seen on here