Vue Documentation Generator

Posted on  by admin

One-stop solution for vue component documentation. This project is supported by our Backers. For detailed documentation: vuese.org.

Vuese Automatically generate documentation for your vue component, and provides a variety of solutions for generating component documentation to meet your different needs.

Ready for More?

@vuese/cli is a command line tool that is very simple to use. If you want to quickly build a documentation site for your vue component or just want to generate markdown document for your vue component, then this tool might be a good choice.

Please go to the details: @vuese/cli. The @vuese/parser module is the parser for the vue component, @vuese/cli internally parsing the vue component via the @vuese/parser module and extract the information we want.

You can do any more advanced things with the interface provided by the @vuese/parser module. For the API documentation, please go to @vuese/parser. Visit the following 👇….

VuePress is composed of two parts: a minimalistic static site generator(opens new window) with a Vue-powered theming system and Plugin API, and a default theme optimized for writing technical documentation.

What is Vue.js?

It was created to support the documentation needs of Vue’s own sub projects.

# How It Works

Each page generated by VuePress has its own pre-rendered static HTML, providing great loading performance and is SEO-friendly.

Yet, once the page is loaded, Vue takes over the static content and turns it into a full Single-Page Application (SPA). Extra pages are fetched on demand as the user navigates around the site.

A VuePress site is in fact a SPA powered by Vue(opens new window), Vue Router(opens new window) and webpack(opens new window).

If you’ve used Vue before, you will notice the familiar development experience when you are writing or developing custom themes (you can even use Vue DevTools to debug your custom theme!).

Declarative Rendering

During the build, we create a server-rendered version of the app and render the corresponding HTML by virtually visiting each route.

This approach is inspired by Nuxt(opens new window)'s nuxt generate command and other projects like Gatsby(opens new window).

  • Each Markdown file is compiled into HTML with markdown-it(opens new window) and then processed as the template of a Vue component.

@vuese/cli

This allows you to directly use Vue inside your Markdown files and is great when you need to embed dynamic content.

Built-in Markdown extensions.

  • Using Vue in Markdown. Vue-powered custom theme system.

Composing with Components

  • Responsive layout. Customizable navbar and sidebar.

Getting Started

  • Nuxt is capable of doing what VuePress does, but it’s designed for building applications.

Conditionals and Loops

  • VuePress is focused on content-centric static sites and provides features tailored for technical documentation out of the box.

Overview

  • Both are great projects and also Vue-powered.

# Why Not ...?

Except they are both fully runtime-driven and therefore not SEO-friendly. If you don’t care for SEO and don’t want to mess with installing dependencies, these are still great choices. Hexo has been serving the Vue docs well - in fact, we are probably still a long way to go from migrating away from it for our main site.

  • The biggest problem is that its theming system is static and string-based - we want to take advantage of Vue for both the layout and the interactivity.

Handling User Input

Also, Hexo’s Markdown rendering isn’t the most flexible to configure. We’ve been using GitBook for most of our sub project docs.

# Features

The primary problem with GitBook is that its development reload performance is intolerable with a large amount of files.

The default theme also has a pretty limiting navigation structure, and the theming system is, again, not Vue based.

The team behind GitBook is also more focused on turning it into a commercial product rather than an open-source tool.

You’re browsing the documentation for v2.x and earlier. For v3.x, click here. Vue (pronounced /vjuː/, like view) is a progressive framework for building user interfaces.

Unlike other monolithic frameworks, Vue is designed from the ground up to be incrementally adoptable.

@vuese/parser

The core library is focused on the view layer only, and is easy to pick up and integrate with other libraries or existing projects. On the other hand, Vue is also perfectly capable of powering sophisticated Single-Page Applications when used in combination with modern tooling and supporting libraries.

If you’d like to learn more about Vue before diving in, we created a video walking through the core principles and a sample project. If you are an experienced frontend developer and want to know how Vue compares to other libraries/frameworks, check out the Comparison with Other Frameworks.

The official guide assumes intermediate level knowledge of HTML, CSS, and JavaScript. If you are totally new to frontend development, it might not be the best idea to jump right into a framework as your first step - grasp the basics then come back!

Online experience

Prior experience with other frameworks helps, but is not required.

Relation to Custom Elements

The easiest way to try out Vue.js is using the Hello World example.

Feel free to open it in another tab and follow along as we go through some basic examples. Or, you can create an index.html file and include Vue with:. The Installation page provides more options of installing Vue.

Note: We do not recommend that beginners start with vue-cli, especially if you are not yet familiar with Node.js-based build tools.

If you prefer something more interactive, you can also check out this tutorial series on Scrimba, which gives you a mix of screencast and code playground that you can pause and play around with anytime.

At the core of Vue.js is a system that enables us to declaratively render data to the DOM using straightforward template syntax:. We have already created our very first Vue app!

This looks pretty similar to rendering a string template, but Vue has done a lot of work under the hood.

The data and the DOM are now linked, and everything is now reactive. How do we know? Open your browser’s JavaScript console (right now, on this page) and set app.message to a different value.

  • You should see the rendered example above update accordingly.
  • Note that we no longer have to interact with the HTML directly.

# GitBook

A Vue app attaches itself to a single DOM element (#app in our case) then fully controls it. The HTML is our entry point, but everything else happens within the newly created Vue instance.

In addition to text interpolation, we can also bind element attributes like this:.

Hover your mouse over me for a few seconds to see my dynamically bound title!

Here we are encountering something new.

The v-bind attribute you are seeing is called a directive. Directives are prefixed with v- to indicate that they are special attributes provided by Vue, and as you may have guessed, they apply special reactive behavior to the rendered DOM.

Here, it is basically saying “keep this element’s title attribute up-to-date with the message property on the Vue instance.”.

# Docsify / Docute

If you open up your JavaScript console again and enter app2.message = 'some new message', you’ll once again see that the bound HTML - in this case the title attribute - has been updated.

# Nuxt

It’s easy to toggle the presence of an element, too:. Go ahead and enter app3.seen = false in the console. You should see the message disappear. This example demonstrates that we can bind data to not only text and attributes, but also the structure of the DOM. Moreover, Vue also provides a powerful transition effect system that can automatically apply transition effects when elements are inserted/updated/removed by Vue.

There are quite a few other directives, each with its own special functionality. For example, the v-for directive can be used for displaying a list of items using the data from an Array:. In the console, enter app4.todos.push({ text: 'New item' }).

You should see a new item appended to the list. To let users interact with your app, we can use the v-on directive to attach event listeners that invoke methods on our Vue instances:.

Note that in this method we update the state of our app without touching the DOM - all DOM manipulations are handled by Vue, and the code you write is focused on the underlying logic. Vue also provides the v-model directive that makes two-way binding between form input and app state a breeze:.

# Hexo

The component system is another important concept in Vue, because it’s an abstraction that allows us to build large-scale applications composed of small, self-contained, and often reusable components.

If we think about it, almost any type of application interface can be abstracted into a tree of components:.

In Vue, a component is essentially a Vue instance with pre-defined options. Registering a component in Vue is straightforward:.

# Ignore examples files

Now you can compose it in another component’s template:. But this would render the same text for every todo, which is not super interesting.

# Public methods

We should be able to pass data from the parent scope into child components. Let’s modify the component definition to make it accept a prop:. Now we can pass the todo into each repeated component using v-bind:.

# Ignoring props

This is a contrived example, but we have managed to separate our app into two smaller units, and the child is reasonably well-decoupled from the parent via the props interface. We can now further improve our component with more complex template and logic without affecting the parent app.

# displayName

In a large application, it is necessary to divide the whole app into components to make development manageable. We will talk a lot more about components later in the guide, but here’s an (imaginary) example of what an app’s template might look like with components:.

You may have noticed that Vue components are very similar to Custom Elements, which are part of the Web Components Spec.

That’s because Vue’s component syntax is loosely modeled after the spec. For example, Vue components implement the Slot API and the is special attribute.

# Methods

However, there are a few key differences:.

The Web Components Spec has been finalized, but is not natively implemented in every browser.

Safari 10.1+, Chrome 54+ and Firefox 63+ natively support web components.

  • In comparison, Vue components don’t require any polyfills and work consistently in all supported browsers (IE9 and above).

When needed, Vue components can also be wrapped inside a native custom element.

Vue components provide important features that are not available in plain custom elements, most notably cross-component data flow, custom event communication and build tool integrations.

# Composable Components

Although Vue doesn’t use custom elements internally, it has great interoperability when it comes to consuming or distributing as custom elements.

Vue CLI also supports building Vue components that register themselves as native custom elements.

We’ve briefly introduced the most basic features of Vue.js core - the rest of this guide will cover them and other advanced features with much finer details, so make sure to read through it all!

Video by Vue Mastery. Watch Vue Mastery’s free Intro to Vue course.

# Example

← InstallationThe Vue Instance →.

Caught a mistake or want to contribute to the documentation?Edit this on GitHub!Deployed onNetlify .

# TypeScript, Flow and Class-style Components

Vue Styleguidist understands TypeScript & Flow annotations. Write components in a typed language, types are documented automatically. It is compatible with class style components as well, with or without TypeScript.

Notice how onClick parameter a does not need type documentation.

# JSX

vue styleguidist understands JSX component templates too. In this example, it will display the definition of the found slot.

# Setup syntax

In vue 3, VueJs introduced the setup syntax(opens new window). This greatly helps readability of components. It also makes a much more performant TypeScript type checking.

From version 4.44.0, Vue Styleguidist allows to document the props & events defined with this syntax.

# Props

In JavaScript, add a comment above the property in the object passed to defineProps(). In this comment, use the same principle as regular syntax Props.

The same goes for TypeScript components:

# Events

Events are all defined using the defineEmits() function. Document them in comments before your events entries.

and in TypeScript

NOTE: Remember to document complex argument types in the comment above the event. Docgen does not parse types and will only display their names.

# Writing code examples

Code examples in Markdown use the ES6 syntax. They can access all the components of your style guide using global variables:

Note: Vue styleguidist uses Bublé(opens new window) to run ES6 code on the frontend, it supports most of the ES6 features(opens new window).

You can also import other modules (e.g. mock data that you use in your unit tests) from examples in Markdown:

Note: If you need a more complex demo, define it in a separate JavaScript file and import it in Markdown. If the component file is in the same folder as the markdown, write import { myExample as exam } from './myExample'; You can then use this imported setup object in your examples. Note that the code for the setup will not appear in the documentation.

Note If you prefer to use JSX in your examples, use the jsxInExample option in your styleguide.config.js. Using this option will force you to use proper Vue format for your examples. No more pseudo-JSX code.

This would not work with the jsxInExample option

...while this would be valid

# Importing examples

To make autocomplete and syntax highlighting practical, one can as well import examples from external files. In the following example ./myExample.vue will be used as an example.

Note This option DOES NOT replace automatically examples code with vue-docgen-cli. Since the rendering engine is only copying the contents of the markdown without parsing it, the CLI can't know what content to replace.

Note No need to specify the language as it will be inferred from the name of the file

Note All flags described here can still be used