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.

Transcript

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

   View Slide

2. HI
   A lil bit about me..
   2
   

   View Slide

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

   View Slide

4. The Journey
   The Journey
   4
   

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

8. What are Static Site Generators?
   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/
   5
   

   View Slide

9. Popularity Trend from 2014 - Present
   6
   

   View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

14. Benefits Of Static Sites
    Benefits Of Static Sites
    Generators
    Generators
    8
    

    View Slide

15. Benefits Of Static Sites
    Benefits Of Static Sites
    Generators
    Generators
    Performance
    8
    

    View Slide

16. Benefits Of Static Sites
    Benefits Of Static Sites
    Generators
    Generators
    Performance
    Secure
    8
    

    View Slide

17. Benefits Of Static Sites
    Benefits Of Static Sites
    Generators
    Generators
    Performance
    Secure
    Easy to Deploy
    8
    

    View Slide

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

    View Slide

19. Gotchas??
    Gotchas??
    9
    

    View Slide

20. Gotchas??
    Gotchas??
    9
    

    View Slide

21. Gotchas??
    Gotchas??
    No server
    9
    

    View Slide

22. Gotchas??
    Gotchas??
    No server
    No complex
    functionality
    9
    

    View Slide

23. #JAMSTACK
    Javascript API's Markup
    10
    

    View Slide

24. #JAMSTACK
    Javascript API's Markup
    10
    

    View Slide

25. #JAMSTACK
    Javascript API's Markup
    Algolia
    Snipcart
    Netlify forms
    Auth0
    Cloudinary
    Disqus
    10
    

    View Slide

26. The Possibilities
    The Possibilities
    Are (Almost)
    Are (Almost)
    Endless
    Endless
    11
    

    View Slide

27. So why Documentation?
    So why Documentation?
    12
    

    View Slide

28. So why Documentation?
    So why Documentation?
    12
    

    View Slide

29. Benefits of Documentation
    Benefits of Documentation
    13
    

    View Slide

30. Benefits of Documentation
    Benefits of Documentation
    It helps keep the team informed
    13
    

    View Slide

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

    View Slide

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

    View Slide

33. Benefits of 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
    13
    

    View Slide

34. Vuepress
    Vuepress
    vuepress.vuejs.org
    14
    

    View Slide

35. Vuepress
    Vuepress
    vuepress.vuejs.org
    Building Blocks
    14
    

    View Slide

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

    View Slide

37. Why should you love
    Why should you love
    VuePress?
    VuePress?
    15
    

    View Slide

38. Why should you love
    Why should you love
    VuePress?
    VuePress?
    Simplicity First
    15
    

    View Slide

39. Why should you love
    Why should you love
    VuePress?
    VuePress?
    Simplicity First
    Fast Performance
    15
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

43. // .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
    16
    

    View Slide

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

    View Slide

45. DEMO TIME
    DEMO TIME
    18
    

    View 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
    

    View Slide

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

    View Slide

48. View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide