当前位置:主页 > 资料 >

In-Depth VuePress Tutorial: Vue-Powered Docs & Blog
栏目分类:资料   发布日期:2018-08-03   浏览次数:

导读:本文为去找网小编(www.7zhao.net)为您推荐的In-Depth VuePress Tutorial: Vue-Powered Docs Blog,希望对您有所帮助,谢谢! In a rush? Skip toor. Have you ever skimmed through the Vue.js documentation? Anyone familiar wit

本文为去找网小编(www.7zhao.net)为您推荐的In-Depth VuePress Tutorial: Vue-Powered Docs & Blog,希望对您有所帮助,谢谢! 去找(www.7zhao.net欢迎您



In a rush? Skip toor.

欢迎访问www.7zhao.net

Have you ever skimmed through the Vue.js documentation? 内容来自www.7zhao.net

Anyone familiar with it will tell you: www.7zhao.net

It's magnificent . 本文来自去找www.7zhao.net

To build it, Evan You,Vue's creator, came up with VuePress.

内容来自www.7zhao.net

For an upcoming side project of ours, we decidedly wanted some of that docs' magic. This post is an account of that process.

欢迎访问www.7zhao.net

You'll learn what VuePress is, what's so great about it, and how to quickly set up a neat Vue.js-powered documentation & blog.

Steps for the technical tutorial: 本文来自去找www.7zhao.net

  1. Installing VuePress.
  2. Generating documentation content.
  3. Adding a blog to VuePress.
  4. Inserting the blog in the navigation.

It's easy & straightforward—you'll be done in no time.

www.7zhao.net

A bit of context for our VuePress project

What's this side project I'm talking about? Well, it started with a pain any blog editor or webmaster knows too well:

www.7zhao.net

Cringe-worthy outreach emails.

You know the kind of email that praises your blog content and offers some guest posts about real estate... on a WEB DEVELOPMENT platform?!

去找(www.7zhao.net欢迎您

本文来自去找www.7zhao.net

C'mon man, try a little harder! copyright www.7zhao.net

We thought it was time to put a spotlight on this stinky marketing technique. To do so, we built a simple static site where anyone can publish anonymous and funny examples of how not to outreach. The name of the site? Outreach Shame . 欢迎访问www.7zhao.net

Note: Outreach Shame isn't live yet, but it presented us with a good use case to build VuePress documentation. You'll find real guidelines in the documentation we created (link further down). Follow them to send us your lousy outreach examples; they'll appear on the site once it goes live.
 copyright www.7zhao.net 

What is VuePress?

In a few words, VuePress is a minimalistic Vue-powered static site generator. www.7zhao.net

本文来自去找www.7zhao.net

As mentioned earlier, the original goal behind its design was to generate documentation, but its system also allows you to write a theme for almost anything.

www.7zhao.net

I've read in a few places that VuePress . Although it does miss some blogging features out-of-the-box, it's still well-suited for simple blogs, as you'll see later on. copyright www.7zhao.net

VuePress is only a few months old but mainly because it comes directly from the brain behind Vue.js. Let's see what about VuePress:

内容来自www.7zhao.net

"It’s special in the sense that it completely uses Vue for its layout and because Vue is a frontend framework it’s actually using a few server-side rendering capabilities to do the static HTML generation. The result is, when you write your layout or your theme for a VuePress site it’s actually a universal application that runs both on the server and on the client."
 去找(www.7zhao.net欢迎您 

The server is skipped though, and every route of the app is virtually rendered to generate static HTML files that load as a Vue.js single page application. 本文来自去找www.7zhao.net

Why should you use VuePress?

As you're probably aware, out there. So where does VuePress stand out?

本文来自去找www.7zhao.net

→ Its unique use of Markdown & Vue components

VuePress handles the conversion of Markdown to HTML by default which makes generating new content very easy. You can even directly in your Markdown files . It allows you to add custom or dynamic features to your website smoothly. Other built-in include a YAML front-matter to set predefined variables or create custom ones that VuePress will automatically interpret. 内容来自www.7zhao.net

→ Its multi-language support from the get-go

Out-of-the-box, VuePress lets you write several versions of your site in as many languages as you need. (!) 欢迎访问www.7zhao.net

→ Its neat default & custom themes

The least I can say is that the VuePress default theme looks clean . It'll do the job for any fast implementation of technical documentation. It's responsive & fully-featured (search capabilities, navbar & sidebar, optional homepage, etc.). Then, or starting from scratch is simple and fun.

copyright www.7zhao.net

Why VuePress over Nuxt.js for a Vue SPA?

copyright www.7zhao.net

If you're into the whole Vue.js ecosystem you surely already know about the framework for universal apps that is . It's way more than a SSG, but its nuxt generate feature allows you to create a static version of an app. VuePress was actually inspired by that exact feature.

去找(www.7zhao.net欢迎您

Both have very different goals. Everything you can do in VuePress you'll also be able to achieve with Nuxt.js. VuePress simplifies the things its good at though, which for the moment include documentation & very small SPAs. If that's all you need, VuePress works wonders, while Nuxt.js might quickly feel overkill.

www.7zhao.net

On the other hand, you couldn't use VuePress for any realapp development. There's no debate you should go with Nuxt.js here.

内容来自www.7zhao.net

Nuxt.js is often mentioned as a great tool to issues. Turns out VuePress does the same to ensure that all content is rendered and crawlable by search engines.

欢迎访问www.7zhao.net

I'll close this argument by saying that I was very impressed by VuePress. It's so simple that I had to think hard about a more complex use case to fill this tuts! copyright www.7zhao.net

Anyway, let's see how it went! ;) 去找(www.7zhao.net欢迎您

VuePress tutorial: Crafting documentation & blog platform

For my use case, I'll go on and use VuePress for Outreach Shame's documentation. While I'm at it, why not add a blog to support the project as well?

copyright www.7zhao.net

Prerequisites:

  • A npm installation
  • A basic understanding of Vue.js

1. Installing VuePress

VuePress is a Node application that needs to be installed via npm or yarn . 本文来自去找www.7zhao.net

Open a terminal and type: copyright www.7zhao.net

npm i -g vuepress 去找(www.7zhao.net欢迎您 

VuePress will then be available directly in your command line. Two useful commands here: 去找(www.7zhao.net欢迎您

vuepress dev
vuepress build
 去找(www.7zhao.net欢迎您 

2. Generating documentation content

You can add VuePress to any repository with a README.md file. This is why VuePress' main selling point is cleaner documentation. copyright www.7zhao.net

At the root of your project, create a README.md file. It's going to be your site index, the home page. My content: copyright www.7zhao.net

# Outreach shame
Outreach Shame is the place to expose every lousy outreach emails. It’s every online marketer’s worst nightmares. These emails are everything you shouldn’t do to promote your business & content. Everything’s kept anonymous for good fun above all.

## How can you contribute?
Simple, forward us the shameful email to *outreachshame@snipcart.com* where it’ll be up for moderation. We kindly ask you to censor any personal information from the email before forwarding it to us. Once your submission is accepted by our team it’ll be published on the site outreachshame.com.

## How it does work?
Once a submission is approved, a commit is pushed in this [GitHub repository](https://github.com/snipcart/outreachshame). We then use [Forestry](https://forestry.io/#/) to make content editing and publishing easier for our dumb marketing folks. Once the entry is published, the site is built and deployed automatically on Netlify. 
去找(www.7zhao.net欢迎您

Then, start your development server: 欢迎访问www.7zhao.net

vuepress dev 

欢迎访问www.7zhao.net

When VuePress is ready, open a browser and navigate to http://localhost:8080 .

内容来自www.7zhao.net

You will see your website with the classy default VuePress theme. 内容来自www.7zhao.net

内容来自www.7zhao.net

It'd be nice to have a title in the navbar, right?

www.7zhao.net

Well, customizing the default VuePress theme with quick configurations is easy peasy.

copyright www.7zhao.net

Start by creating a folder named .vuepress at the root of your project's folder. In this folder, add a file named config.js . This file will be used to customize the website; it's basically a JavaScript file that should export a JSON object. 去找(www.7zhao.net欢迎您

// /.vuepress/config.js

module.exports = {
    title: 'Outreach Shame'
} 去找(www.7zhao.net欢迎您 

If you reload your website, you'll see the title in the top left corner of the navbar. www.7zhao.net

3. Adding a blog to VuePress

As you can see, it's a walk in the park to build custom documentation for a project using VuePress. So let's push it further a bit and add a blog. www.7zhao.net

As I wrote earlier, VuePress allows you to write custom Vue components that can be inserted into any Markdown files. In this case, I'll build a component that will render the list of blog posts. 内容来自www.7zhao.net

Create a folder named components in the .vuepress folder. You'll add your components in there. They'll then be automatically available globally; no need to import them.

内容来自www.7zhao.net

Somehow VuePress has it covered.

copyright www.7zhao.net

Create a file named BlogIndex.vue —VuePress components use the single file component pattern. 去找(www.7zhao.net欢迎您

A component created in a VuePress application gets some computed properties out of the box. You can access this.$site which gives you metadata of the website, with each page in it. This is going to be useful in this case because this is how we'll get the blog posts. 内容来自www.7zhao.net

You also have this.$page giving you information about the current page context.

www.7zhao.net

Here is the code you will need in your component file:

欢迎访问www.7zhao.net

<!-- /.vuepress/components/BlogIndex.vue -->

<template>
<div>
    <div v-for="post in posts">
        <h2>
            <router-link :to="post.path">{{ post.frontmatter.title }}</router-link>
        </h2>
        
        <p>{{ post.frontmatter.description }}</p>

        <p><router-link :to="post.path">Read more</router-link></p>
    </div>
</div>
</template>

<script>
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));
        }
    }
}
</script> 

本文来自去找www.7zhao.net

The template itself is pretty basic. I iterated through the list of posts and listed them all. I'm using the router-link component available through vue-router that VuePress comes equipped with.

内容来自www.7zhao.net

I added a computed property named posts . This property gets all the blog posts from the site pages. When you create new blog posts, you'll need to specify some front matter information, such as the post date. Newest posts will appear first.

本文来自去找www.7zhao.net

The component is ready! Now you'll need to add some content. 去找(www.7zhao.net欢迎您

Create a folder named blog at the root of the project. In this folder, add a README.md file. This is going to be the blog index, and this is where you'll include the BlogIndex component. 内容来自www.7zhao.net

---
blog_index: true
---

# Blog

Welcome on Outreach shame blog

<BlogIndex /> 

www.7zhao.net

The blog_index front matter will be used to make sure that the blog index isn't listed in the posts. I'm using it when filtering the posts in the posts computed property of the BlogIndex component. copyright www.7zhao.net

Notice how easy it is to include a custom component. It's registered automatically by VuePress and can be included in any markdown file.

内容来自www.7zhao.net

Next step is to add a first blog post. In the blog folder, create a filed named first-post.md . 内容来自www.7zhao.net

You'll have to define a couple of frontmatter settings:

copyright www.7zhao.net

<!-- /blog/first-post.md -->
---
title: Bacon ipsum dolor amet hamburger pancetta ball tip
date: 2018-07-28
description:
    Kielbasa tenderloin boudin bacon cupim, pastrami strip steak rump picanha meatloaf venison meatball ribeye. Burgdoggen t-bone jowl venison biltong andouille. Turducken shankle tongue landjaeger drumstick, pancetta porchetta. Brisket ham turkey andouille picanha. Pancetta chuck shank ham.
---

# First post

/* Your awesome content goes here */ 
copyright www.7zhao.net

The properties title , description and date are important; they will be used when listing blog posts. Every post in the blog folder should have these defined. 欢迎访问www.7zhao.net

4. Inserting the blog in the VuePress navigation

The last step will be to make the blog available via the navigation bar.

内容来自www.7zhao.net

Open /.vuepress/config.js file again and add: 本文来自去找www.7zhao.net

// /.vuepress/config.js

module.exports = {
    title: 'Outreach Shame',
    themeConfig: {
        nav: [
            { text: 'Home', link: '/' },
            { text: 'Blog', link: '/blog/' }
        ]
    }
} 
内容来自www.7zhao.net

You'll need to specify the nav bar elements in the themeConfig property. copyright www.7zhao.net

Then, reload your website and click on the blog navigation item, you should have something like this:

本文来自去找www.7zhao.net

copyright www.7zhao.net

Live demo & GitHub repo

去找(www.7zhao.net欢迎您

See the live demo

去找(www.7zhao.net欢迎您

See GitHub repo

www.7zhao.net

Closing thoughts

VuePress is so awesomely straightforward. I only spent around two hours building this demo, and that includes learning how VuePress works. It might just be the best tool out there to document your open source project or library.

内容来自www.7zhao.net

Having the ability to use Vue components on top of that is a huge bonus. We're currently working on the third version of our shopping cart and this experiment forces me to seriously consider using VuePress to build its documentation! 本文来自去找www.7zhao.net

However, as working with it confirmed, I don't think you should use VuePress to build applications. Frameworks like Nuxt and Gatsby would be better options to develop a more complex application. 本文来自去找www.7zhao.net

If you've enjoyed this post, please take a second to. Got comments, questions? Hit the section below! copyright www.7zhao.net

欢迎访问www.7zhao.net


本文原文地址:https://snipcart.com/blog/vuepress-tutorial-vuejs-documentation

以上为In-Depth VuePress Tutorial: Vue-Powered Docs & Blog文章的全部内容,若您也有好的文章,欢迎与我们分享! 欢迎访问www.7zhao.net

Copyright ©2008-2017去找网版权所有   皖ICP备12002049号-2 皖公网安备 34088102000435号   关于我们|联系我们| 免责声明|友情链接|网站地图|手机版