Tutorial

Document Your Vue.js Components with Propdoc

Published on May 30, 2017
Default avatar

By Joshua Bemenderfer

Document Your Vue.js Components with Propdoc

While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the “report an issue“ button at the bottom of the tutorial.

Every developer wants to read good documentation. Every developer wants to write good documentation. Few developers actually do. Let’s take a look at a really simple way to both generate documentation for your Vue.js components and render it as well with propdoc.

Installation

Install propdoc like any other Vue plugin: via Yarn or NPM.

# Yarn
$ yarn add propdoc

# NPM
$ npm install propdoc --save

Documenting Components

The biggest feature of propdoc is the ability to write your documentation as properties on components. These are only used if you use propdoc to render the documentation. Otherwise they have no effect. It’s a genius idea that I’m surprised doesn’t seem to have been done before.

MyButton.vue
<template>
  <div class="my-button" :class="{
    flat: isFlat,
    raised: isRaised,
    primary: isPrimary
  }">
    <slot></slot>
  </div>
</template>

<script>

export default {
  name: "my-button",
  introduction: "A basic example button.",
  description: "A basic button with the ability to be flat, raised, or be a primary button. Nothing super special. (I stink at writing documentation.)",
  token: `<my-button isFlat isPrimary>Button Text</my-button>`,

  props: {
    isFlat: {
      type: Boolean,
      default: false,
      note: 'Whether or not to use the flat version of the button. (No gradient or outline.)'
    },

    isRaised: {
      type: Boolean,
      default: true,
      note: 'Whether or not to use the raised version of the button. (Has a drop shadow.)'
    },

    isPrimary: {
      type: Boolean,
      default: false,
      note: 'Whether or not to use the primary coloring.'
    }
  }
}

</script>

Along with the usual built-in keys like name and required on the component and props, propdoc adds a few more:

  • note: Tells what a prop does.
  • introduction: A quick introduction to a component.
  • description: A detailed description of the component. Supports Markdown.
  • token: A bit of code demonstrating how to use the component.

Rendering Documentation

It’s nice and easy to render out the documentation for your component too. Just add the propDoc component and pass your documented component to it in the component prop.

DocumentationComponent.vue
<template>
  <div>
    <!-- Render the documentation for MyButton -->
    <prop-doc :component="MyButton"></prop-doc>
  </div>
</template>

<script>
import propDoc from 'propdoc';
import MyButton from './MyButton.vue';

export default {
  components: {
    propDoc
  },

  data() {
    return {
      MyButton
    }
  }
}
</script>

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us


About the authors
Default avatar
Joshua Bemenderfer

author

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
 
Leave a comment


This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel