CRAFTING RICH DOCUMENTATION WITH VUEPRESS

Concatenate Conference August 2018

@lauragift21,  giftegwuenu.com

HI

A lil bit about me..

Gift Egwuenu

Software Developer @Andela

Open Source Contributor @okkurLabs

@lauragift21

The Journey

  • An Overview of Static sites and Static Site generators
  • Why Documentation?
  • Hello Vuepress...

What are Static Site Generators?

Static Site Generators are a new, hybrid approach to web development that allows you to build a powerful, website locally on your computer but pre-builds the site into static files for deployment.

Popularity Trend from 2014 - Present

  • Hugo
  • Gatsby
  • Vuepress

Benefits Of Static Sites Generators

  • Performance
  • Secure
  • Easy to Deploy
  • SEO Friendly

Gotchas??

  • No server

  • No complex functionality

Javascript API's Markup

 

  • Algolia
  • Snipcart
  • Netlify forms
  • Auth0
  • Cloudinary
  • Disqus

The Possibilities Are (Almost) 

Endless

So why Documentation?

Benefits of ​Documentation

 

  • It helps keep the team informed
  • Maintaining Open Source software
  • Onboarding new team members
  • Better opportunities for the team to remember things

Vuepress

Vue Router

Webpack

Vue

Building Blocks

 

Why should you love VuePress?

  • Simplicity First
  • Fast Performance
  • Automatic Service Worker
  • Multiple Language Support
  • Google Analytics out of the box
// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'External', link: 'https://google.com' },
    ]
  }
}

THEMING

// .vuepress/config.js
module.exports = {
  themeConfig: {
    algolia: {
      apiKey: '1eb37de6308abdccf9b760ddacb418b4',
      indexName: 'qwerty'
    }
  }
}

Navbar configuration

Custom Algolia Search

SHOWCASE

DEMO TIME

Getting Started

// install vuepress globally
$ yarn global add vuepress 

# create a markdown file
echo '# Hello VuePress' > README.md

# start writing
vuepress dev

# build to static files
vuepress build
.
├─ docs
│  ├─ README.md
│  └─ .vuepress
│     └─ config.js
└─ package.json

Project Structure

  • .vuepress/config.js(config center)
  • README.md (manage content)
  • package.json(manage dependencies)

Deployment

  • Github pages
  • Netlify
  • Surge
  • Now
  • Firebase
// package.json
{
  "scripts": {
    "doc:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

RESOURCES

THANK YOU :)

Slides:
bit.ly/vuepress

Questions??