Crafting Rich Documentation with Vuepress

A presentation at Concatenate in August 2018 in Lagos, Nigeria by Egwuenu Gift

Slide 1

Slide 1

CRAFTING RICH DOCUMENTATION WITH VUEPRESS Concatenate Conference August 2018 @lauragift21, giftegwuenu.com 1

Slide 2

Slide 2

HI A lil bit about me.. 2

Slide 3

Slide 3

Gift Egwuenu Software Developer @Andela Open Source Contributor @okkurLabs giftegwuenu.com @lauragift21 3

Slide 4

Slide 4

The Journey 4

Slide 5

Slide 5

The Journey An Overview of Static sites and Static Site generators 4

Slide 6

Slide 6

The Journey An Overview of Static sites and Static Site generators Why Documentation? 4

Slide 7

Slide 7

The Journey An Overview of Static sites and Static Site generators Why Documentation? Hello Vuepress... 4

Slide 8

Slide 8

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 prebuilds the site into static files for deployment. https://wsvincent.com/what-is-a-static-site-generator/ 5

Slide 9

Slide 9

Popularity Trend from 2014 - Present 6

Slide 10

Slide 10

Staticgen.com https://www.staticgen.com/ 7

Slide 11

Slide 11

Staticgen.com Hugo https://www.staticgen.com/ 7

Slide 12

Slide 12

Staticgen.com Hugo Gatsby https://www.staticgen.com/ 7

Slide 13

Slide 13

Staticgen.com Hugo Gatsby Vuepress https://www.staticgen.com/ 7

Slide 14

Slide 14

Benefits Of Static Sites Generators 8

Slide 15

Slide 15

Benefits Of Static Sites Generators Performance 8

Slide 16

Slide 16

Benefits Of Static Sites Generators Performance Secure 8

Slide 17

Slide 17

Benefits Of Static Sites Generators Performance Secure Easy to Deploy 8

Slide 18

Slide 18

Benefits Of Static Sites Generators Performance Secure Easy to Deploy SEO Friendly 8

Slide 19

Slide 19

Gotchas?? 9

Slide 20

Slide 20

Gotchas?? 9

Slide 21

Slide 21

Gotchas?? No server 9

Slide 22

Slide 22

Gotchas?? No server No complex functionality 9

Slide 23

Slide 23

#JAMSTACK Javascript API's Markup 10

Slide 24

Slide 24

#JAMSTACK Javascript API's Markup 10

Slide 25

Slide 25

#JAMSTACK Javascript API's Markup Algolia Snipcart N e t l i f y fo r m s Au t h 0 Cloudinary Disqus 10

Slide 26

Slide 26

The Possibilities Are (Almost) Endless 11

Slide 27

Slide 27

So why Documentation? 12

Slide 28

Slide 28

So why Documentation? 12

Slide 29

Slide 29

Benefits of Documentation 13

Slide 30

Slide 30

Benefits of Documentation It helps keep the team informed 13

Slide 31

Slide 31

Benefits of Documentation It helps keep the team informed Maintaining Open Source software 13

Slide 32

Slide 32

Benefits of Documentation It helps keep the team informed Maintaining Open Source software Onboarding new team members 13

Slide 33

Slide 33

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 13

Slide 34

Slide 34

Vuepress vuepress.vuejs.org 14

Slide 35

Slide 35

Vuepress vuepress.vuejs.org Building Blocks 14

Slide 36

Slide 36

Vuepress vuepress.vuejs.org Building Blocks Vue Webpack Vue Router 14

Slide 37

Slide 37

Why should you love VuePress? 15

Slide 38

Slide 38

Why should you love VuePress? Simplicity First 15

Slide 39

Slide 39

Why should you love VuePress? Simplicity First Fast Performance 15

Slide 40

Slide 40

Why should you love VuePress? Simplicity First Fast Performance Automatic Service Worker 15

Slide 41

Slide 41

Why should you love VuePress? Simplicity First Fast Performance Automatic Service Worker Multiple Language Support 15

Slide 42

Slide 42

Why should you love VuePress? Simplicity First Fast Performance Automatic Service Worker Multiple Language Support Google Analytics out of the box 15

Slide 43

Slide 43

THEMING // .vuepress/config.js module.exports = { themeConfig: { nav: [ { text: 'Home', link: '/' }, { text: 'Guide', link: '/guide/' }, { text: 'External', link: 'https://google.com' }, ] } } Custom Algolia Search Navbar configuration // .vuepress/config.js module.exports = { themeConfig: { algolia: { apiKey: '1eb37de6308abdccf9b760ddacb418b4', indexName: 'qwerty' } } } 16

Slide 44

Slide 44

SHOWCASE Vue cli Vuex Vue-server-renderer Vue router Vue-test-utils Vue loader Laravel Nova 17

Slide 45

Slide 45

DEMO TIME 18

Slide 46

Slide 46

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 19

Slide 47

Slide 47

Project Structure .vuepress/config.js(config center) README.md (manage content) package.json(manage dependencies) . ├─ │ │ │ └─ docs ├─ README.md └─ .vuepress └─ config.js package.json 20

Slide 48

Slide 48

21

Slide 49

Slide 49

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

Slide 50

Slide 50

DEMO bit.ly/vuepress-demo REPO bit.ly/vuepress-repo 23

Slide 51

Slide 51

RESOURCES https://staticgen.com https://vuepress.vuejs.org https://github.com/vuejs/vuepress https://github.com/myles/awesomestatic-generators https://www.thenewdynamic.org/ https://jamstack.org/ 24

Slide 52

Slide 52

Slides: bit.ly/vuepress Questions?? THANK YOU :) giftegwuenu.com @lauragift21 on twitter 25