Have you ever skimmed through the Vue.js documentation? Anyone familiar with it will tell you: It's . magnificent To build it, Evan You, 's creator, came up with VuePress. Vue For an upcoming side project of ours, we decidedly wanted some of that docs' magic. This post is an account of that process. You’ll learn what VuePress is and what’s so great about it. You’ll learn how to quickly set up a neat Vue.js-powered documentation & blog. Steps for the technical tutorial: Installing VuePress. Generating documentation content. Adding a blog to VuePress. Inserting the blog in the navigation. It's easy & straightforward—you'll be done in no time. 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: 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?! C’mon man, try a little harder! We thought it was time to put a spotlight on this stinky 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? . marketing Hugo Outreach Shame Note: Outreach Shame isn’t live yet. 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. What is VuePress? In a few words, VuePress is a minimalistic Vue-powered static site generator. As mentioned earlier, the original goal behind its design was to generate documentation. Its system also allows you to write a theme for almost anything. 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. is not blog-aware yet 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: has already made some waves the man has to say “It’s special in the sense that it completely uses Vue for its layout. 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.” The server is skipped though. Every route of the app is virtually rendered to generate static HTML files that load as a Vue.js single page application. Why should you use VuePress? As you're probably aware, out there. So where does VuePress stand out? there are tons of static site generators → Its unique use of Markdown & Vue components VuePress handles the conversion of Markdown to HTML by default. This makes generating new content very easy. . 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. You can even use Vue components directly in your Markdown files Markdown features → 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. (!) → Its neat default & custom themes The least I can say is that the VuePress default theme looks . 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. clean customizing the default theme Why VuePress over Nuxt.js for a Vue SPA? 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 an SSG, but its feature allows you to create a static version of an app. VuePress was inspired by that exact feature. Nuxt.js nuxt generate 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. On the other hand, you couldn't use VuePress for any real . There's no debate you should go with Nuxt.js here. app development Nuxt.js is often mentioned as a great tool to issues. It turns out VuePress does the same to ensure that all content is rendered and crawlable by search engines. handle Vue.js SPA SEO 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! Anyway, let's see how it went! ;) 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? Prerequisites: Have npm installed A basic understanding of Vue.js 1. Installing VuePress VuePress is a Node application that needs to be installed via or . npm yarn Open a terminal and type: npm i -g vuepress VuePress will then be available directly in your command line. Two useful commands here: starts a development server with automatic reload and all the dev goodies. This is the command you'll use when developing your website. vuepress dev builds your website. The generated assets will be ready to deploy on any hosting service. vuepress build 2. Generating documentation content You can add VuePress to any repository with a file. This is why VuePress' main selling point is cleaner documentation. README.md At the root of your project, create a file. It's going to be your site index, the home page. My content: README.md # 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. Then, start your development server: vuepress dev When VuePress is ready, open a browser and navigate to . http://localhost:8080 You will see your website with the classy default VuePress theme. It'd be nice to have a title in the navbar, right? Well, customizing the default VuePress theme with quick configurations is easy peasy. Start by creating a folder named at the root of your project's folder. In this folder, add a file named . This file will be used to customize the website. It's basically a file that should export a JSON object. .vuepress config.js JavaScript If you reload your website, you'll see the title in the top left corner of the navbar. 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. 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. Create a folder named in the folder. You'll add your components in there. They'll then be automatically available globally; no need to import them. components .vuepress Somehow VuePress has it covered. Create a file named —VuePress components use the single file component pattern. BlogIndex.vue A component created in a VuePress application gets some computed properties out of the box. You can access 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. this.$site You also have giving you information about the current page context. this.$page Here is the code you will need in your component file: The template itself is pretty basic. I iterated through the list of posts and listed them all. I'm using the component available through that VuePress comes equipped with. router-link vue-router I added a computed property named . 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. posts The component is ready! Now you'll need to add some content. Create a folder named at the root of the project. In this folder, add a file. This is going to be the blog index, and this is where you'll include the component. blog README.md BlogIndex --- blog_index: true --- 

# Blog 

Welcome on Outreach shame blog 

<BlogIndex /> The 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 computed property of the component. blog_index posts BlogIndex Notice how easy it is to include a custom component. It's registered automatically by VuePress and can be included in any markdown file. Next step is to add a first blog post. In the folder, create a filed named . blog first-post.md You'll have to define a couple of frontmatter settings: --- 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 */ The properties , and are important. They will be used when listing blog posts. Every post in the folder should have these defined. title description date blog 4. Inserting the blog in the VuePress navigation The last step will be to make the blog available via the navigation bar. Open file again and add: /.vuepress/config.js You'll need to specify the nav bar elements in the property. themeConfig Then, reload your website. Click on the blog navigation item, you should have something like this: Live demo & GitHub repo See the live demo here See GitHub repo here Closing thoughts VuePress is straightforward. I only spent around two hours building this demo. That includes learning how VuePress works. It might just be the best tool out there to document your open source project or library. 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. This experiment forces me to seriously consider using VuePress to build its documentation! 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. If you've enjoyed this post, please take a second to share it on Twitter . Got comments, questions? Hit the section below! I originally published this on the Snipcart blog and shared it in our newsletter .

Waves

Ball

NuxtJS

Deep Dive into VuePress: Craft a Clean Documentation & Blog

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Build a Gatsby & GraphQL App on Top of a Headless CMS

100 Stories To Learn About Blogging

24 Best JavaScript Blogs and Websites

2018: My Technology Retrospective

4 Simple Ways to Skyrocket Your Blog Readership

46 Stories To Learn About Blog

Build a Gatsby & GraphQL App on Top of a Headless CMS

100 Stories To Learn About Blogging

24 Best JavaScript Blogs and Websites

2018: My Technology Retrospective

4 Simple Ways to Skyrocket Your Blog Readership

46 Stories To Learn About Blog

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps