CRAFTING RICH DOCUMENTATION WITH VUEPRESS

Concatenate Conference August 2018

@lauragift21,  giftegwuenu.com

HI

A lil bit about me..

Gift Egwuenu

giftegwuenu.com

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.

https://wsvincent.com/what-is-a-static-site-generator/

Popularity Trend from 2014 - Present

Staticgen.com

  • Hugo
  • Gatsby
  • Vuepress

Benefits Of Static Sites Generators

  • Performance
  • Secure
  • Easy to Deploy
  • SEO Friendly

Gotchas??

  • No server

  • No complex functionality

#JAMSTACK

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

vuepress.vuejs.org

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

Vue cli

Vuex

Vue-server-renderer

Vue router

Vue-test-utils

Vue loader

Laravel Nova

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"
  }
}

REPO

bit.ly/vuepress-repo

DEMO

bit.ly/vuepress-demo

RESOURCES

THANK YOU :)

giftegwuenu.com

@lauragift21 on twitter

Slides:
bit.ly/vuepress

Questions??

CRAFTING RICH DOCUMENTATION WITH VUEPRESS

By Gift Egwuenu

CRAFTING RICH DOCUMENTATION WITH VUEPRESS

This talk will be focused on the problems with documenting software and how you can leverage Vuepress as a solution for writing rich documentation. You’ll also learn the features of Vuepress and how it differs from other static site generators.

  • 3,772

More from Gift Egwuenu