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
- Provide examples as much as you can
- Keep it simple
Block Types #
Page title is mandatory for documentation pages.
Used for examples, API, FAQ. Think about it as
headline block is used to mark the titles of examples and the FAQs. Think about it as
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:
Paragraph (example). Link in the text leading to an external resource: markdown-it-attrs.
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]].')
Should be used for lists.
- Value of list item 1
- Value of list item 2
block.list(['Value of list item 1', 'Value of list item 2'])
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
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.
types: '(value: boolean) => void',
types: '() => void',
Used to display tabular data. Requires a flat column-definitions array and yet another two-dimensional-array with the actual cells' data.
Used for relative (local) links processed by the router (with options or without them).
block.link('Link (example)', '/getting-started/configuration-guide#components-config')
Used to display an important message.
block.alert('Alert (example)', 'danger')