We just released Vuestic Admin 3.0 🤗
🔥🔥🔥 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:

code-examples
[code-examples].ts
index.ts
examples
[example].vue
components
[component].vue
api-options.ts
page-config.ts

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
#

Title
#

Page title is mandatory for documentation pages.

Title (example)
#

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

Subtitle
#

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

Subtitle (example)
#

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

Headline
#

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)')

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

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](https://github.com/arve0/markdown-it-attrs)[[target=_blank]].')

List
#

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'])

Code
#

For the code previews we use highlight.js.

<div>Code string</div>
Open in GitHub
block.code('
  <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, 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',
    },
  },
}

Table
#

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

col1col2col3col4
d1C1d1C2

d1C3

d1C4

d2C1d2C2

d2C3

d2C4

d3C1d3C2

d3C3

d3C4

Open in GitHub
block.table(columns, tableData)

Link
#

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

Link (example)

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

Alert
#

Used to display an important message.

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