Official Partner of
Nuxt
๐Ÿ”ฅ๐Ÿ”ฅ๐Ÿ”ฅ Hire us

Working with documentation
#

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

Introduction
#

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:

api-options.ts
page-config.ts

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

Generators
#

We have created custom generators to facilitate and automate the creation of new pages..

  • The yarn generate:docspage command will generate a page with the specified name in the category selected from the list..
  • The yarn generate:component command will generate a complete structure for a new component: create a component, connect it to a library, make a configuration file for it, and add a clean example to the examples folder.

Block Types
#

Title
#

Page title is mandatory for documentation pages.

block.title('translation.path')

Compiles to:

Title (example)
#

Subtitle
#

Used for examples, API, FAQ. Think h2.

block.subtitle('translation.path')

Compiles to:

Subtitle (example)
#

Headline
#

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

block.headline('translation.path')

Compiles to:

Headline (example)
#

Paragraph
#

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

block.paragraph('translation.path')

Compiles to:

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

List
#

Should be used for lists.

block.list(['translation1.path', 'translation2.path'])

Compiles to:

  • Value of list item 1
  • Value of list item 2

Here's the resulting markup for the code above:

<ul>
  <li>List item 1</li>
  <li>List item 2</li>
</ul>

Code
#

For the code previews we use highlight.js.

block.code('
<div>Code string</div>
')

Compiles to:

<div>Code string</div>

Example
#

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.

block.example('ComponentName')

Component
#

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

block.component('ComponentName')

API
#

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

block.api(VaComponent, 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',
    },
  },
}

Table
#

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

columns = [
  "col1",
  { title: "col2", type: "strong" },
  { title: "col3", type: "markdown" },
  { title: "col4", type: "code" },
];

tableData = [
  [
    "d1C1",
    "d1C2",
    "[d1C3](https://en.wikipedia.org/wiki/Markdown)[[target=_blank]]",
    "d1C4",
  ],
  ["d2C1", "d2C2", "<mark>d2C3</mark>", "d2C4"],
  ["d3C1", "d3C2", "~~d3C3~~", "d3C4"],
];
block.table(columns, tableData)

Compiles to:

col1col2col3col4
d1C1d1C2

d1C3

d1C4

d2C1d2C2

d2C3

d2C4

d3C1d3C2

d3C3

d3C4

Link
#

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

options = {
  preText: "prefix with **markdown** text",
  afterText: "suffix",
};
block.link('translation.path', '/contribution/documentation-page#introduction', options)
block.link('translation.path', '/getting-started/configuration-guide#components-config')

Compiles to:

prefix with markdown text
Link with options (example)
suffix

Link (example)

Alert
#

Used to display an important message.

block.alert('translation.path', 'danger')

Compiles to: