Upgrade to Pro — share decks privately, control downloads, hide ads and more …

CRAFTING RICH DOCUMENTATION WITH VUEPRESS

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.

Gift Egwuenu

August 11, 2018
Tweet

More Decks by Gift Egwuenu

Other Decks in Programming

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. 21

    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