Working with documentation #
This page is intended for Vuestic-UI contributors. It explains the ways to create and modify the documentation.
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.
We have created custom generators to facilitate and automate the creation of new pages…
yarn generate:docspagecommand will generate a page with the specified name in the category selected from the list…
yarn generate:componentcommand 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 #
Page title is mandatory for documentation pages.
Title (example) #
Used for examples, API, FAQ. Think
Subtitle (example) #
headline block is used to mark the titles of examples and the FAQs. Think
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:
Paragraph (example). Link in the text leading to an external resource: markdown-it-attrs.
Should be used for lists.
- Value of list item 1
- Value of list item 2
Here’s the resulting markup for the code above:
For the code previews we use prism.
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.
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.
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).
prefix with markdown text
Used to display an important message.