Working with documentation

This page is intended for Vuestic-UI contributors. It explains the ways to create and modify the documentation.


Instead of using the established documentation system, such as vue-press or docsify, we decided to build a system specifically tailored for Vuestic. Itโ€™s meant to provide an excellent flexibility for the future growth.

Page Config

The page configuration must be located in a specific path, which is similar to the page URL. The folder with the page configuration must include the components folders for blocks with components and examples for blocks with examples. These folders should contain the * .vue files. An example of the structure and directory of the configuration folder for the current page:


The configuration file contains config, which is an array of page blocks that perform specific functions.

Component page structure

It is example of perfect component page structure. You can use it as a template for your component page. Not all blocks here required of course, but better to have them all.

  • title - page title, component name
  • paragraph - page description
  • subtitle - "When to use"
  • list - List of examples
  • subtitle - "Examples"
  • example - List of examples
  • subtitle - "Accessibility"
  • paragraph - keyboard navigation
  • paragraph - additional information
  • subtitle - "API"
  • api - component api or table for manual api
  • subtitle - "FAQ"
  • headline - List of questions covered by paragraph with the answer

Pages in Services, Getting Started, e.g. don't actually have a structure, but here are general rules

  • Add description paragraph after title and subtitle
  • Provide examples as much as you can
  • Keep it simple

Block Types


Page title is mandatory for documentation pages.

Title (example)

Open in GitHub
block.title('Title (example)')


Used for examples, API, FAQ. Think about it as h2.

Subtitle (example)

Open in GitHub
block.subtitle('Subtitle (example)')


The headline block is used to mark the titles of examples and the FAQs. Think about it as h3.

Headline (example)

Open in GitHub
block.subtitle('Headline (example)')


Should be used for all the regular text blocks. For links to external resources you can specify the target attribute in markdown markup as follows: [name](href)[[target=_blank]].

Paragraph (example). Link in the text leading to an external resource: markdown-it-attrs.

Open in GitHub
block.paragraph('Paragraph (example). Link in the text leading to an external resource: [markdown-it-attrs]([[target=_blank]].')


Should be used for lists.

  • Value of list item 1
  • Value of list item 2
Open in GitHub
block.list(['Value of list item 1', 'Value of list item 2'])


For the code previews we use highlight.js.

<div>Code string</div>
Open in GitHub
  <div>Code string</div>


Shows a component with code preview. Component can use all global services: css classes, colors etc. Mostly used in the ui-elements section to show examples of use.



Shows a component that has some logic and is not an example of use.



The API-documentation for a component. Combines component options with manual declarations.

block.api(VaComponent, apiDescription, apiOptions)

API Options

We can't go too far with the help of automated code analysis. Most of the API documentation has to be declared explicitly. API options allow you to configure things such as: version, props, events, methods and slots.

hidden - allows you to hide the prop from the API section of the documentation page. Might become quite useful for some props which are intended for internal use solely.

types - the documentation engine can automatically infer simple prop types (such as String, Number, etc.) right from the component options. Almost any other type should be defined explicitly.

version - specifies the version of Vuestic UI that this component or feature has been introduced at.

  version: '1.1',
  props: {
    value: {
      hidden: false,
      types: 'String',
      version: '1.0',
  events: {
    input: {
      types: '(value: boolean) => void',
      version: '1.0',
  methods: {
    hide: {
      types: '() => void',
      version: '1.0',
  slots: {
    default: {
      version: '1.0',


Used to display tabular data. Requires a flat column-definitions array and yet another two-dimensional-array with the actual cells' data.









Open in GitHub
block.table(columns, tableData)


Used for relative (local) links processed by the router (with options or without them).

Open in GitHub'Link (example)', '/getting-started/configuration-guide#components-config')


Used to display an important message.

Open in GitHub
block.alert('Alert (example)', 'danger')