Styleguidist does not load a main.js file. To install plugins and component libraries, you will need to require then somewhere else.
First create a .js file that installs the plugins. Then add it into the styleguide.config.js file require option:
styleguide.config.js
styleguide/global.requires.js
If you need to change the root component of each preview example, you can change the root component of the preview. Creating a .js file that exports the root component as jsx component (opens new window) and then adds it into the styleguide.config.js file
Use renderRootJsx option:
See an example of style guide with vuetify and vue-i18n (opens new window).
NOTE Since Styleguidist creates one root per example (for isolation), installing Vuetify with the default optimized way will not work. Instead, you should prefer installing it globally by following the setup above.
# How to add vuex to the style guide?You can add it, creating a .js file that installs the plugins and then adds it into the styleguide.config.js file
Use require option:
See an example of style guide with vuex (opens new window).
# How to add dummy data to the style guide?You can use global mixins (opens new window) to add dummy data:
Use require option:
# How to exclude some components from the style guide?Vue Styleguidist will ignore tests (__tests__ folder) by default.
Use ignore option to customize this behavior:
# How to hide some components in a style guide but make them available in examples?Note: You should pass glob patterns, for example, use
**/components/Button.vueinstead ofcomponents/Button.vue.
Problem: I do not want to document any component whose filename starts with an underscore (_).
If you started with a vue-cli install, or just installed styleguidist, docs/install.components.js the file metionned in the require option does not exist in your codebase.
NOTE
docs/install.components.jsabove is a file name we chose. It matters not to styleguidist what name you choose so choose one that makes sense to you.
First we create docs/install.components.js. Then, we will use the node 6 function require (or require.context since we are in webpack context) to gather the components we want to use in examples.
Finally, we will register them using the Vue.component() function.
The components starting with an underscore are now available in every example (without the underscore).
# How to add custom JavaScript and CSS or polyfills?In your style guide config:
# How to change styles of a style guide?There are two config options to change your style guide UI: theme and styles.
Use theme to change fonts, colors, etc.
Use styles to tweak the style of any particular Styleguidist component.
As an example:
Note: See available theme variables (opens new window).
Note: Styles use JSS (opens new window) with these plugins: jss-isolate (opens new window), jss-nested (opens new window), jss-camel-case (opens new window), jss-default-unit (opens new window), jss-compose (opens new window) and jss-global (opens new window).
Note: Use React Developer Tools (opens new window) to find component and style names. For example a component
<LogoRenderer><h1 className="rsg--logo-53">corresponds to an example above.
Note: Use a function instead of an object for styles to access all theme variables in your custom styles.
# How to change style guide dev server logs output?NOTA: If you need to reference the original component, you can do so by importing the
rsg-components-defaultversion. Check out the customized (opens new window) example, it uses the following:
You can modify webpack dev server logs format changing stats option of webpack config:
debugger; statement wherever you want: in a component source, a Markdown example or even in an editor in a browser.debugger; statement at the beginning of your code.First read Vagrant guide (opens new window) from the webpack documentation. Then enable polling in your webpack config:
# How to document styled-components?To document styled-components you need to get them recognized by vue-docgen-api. The simplest way is to use extends:
or if you are using with the class component syntax
# Use vue-styleguidist with components that contain routingIf your components contain <router-link> the best way is, in your styleguide to mock it. In the styelguide.config,js file add styleguide.global.required.js (see below) to the require parameter. Styleguidist will render router-link as an anchor or tag of your choosing. Don't use vue-router inside vue-styleguidist. It will conflict with its internal router.
See this example for a concrete implementation.
# How to include FontAwesome (or other icon sets) in your style guidePRO TIP: If your styleguide has
.resolveissues in the browser console, it still seems to be using vue-router. Check if you are requiring therouter.jsfile in any of the showcased components and remove the dependency. If you still can't find the culprit, follow these steps and you will find it.
- Find all mentions of
Vue.use(Router)in your codebase- Add
console.trace()on the line before it to get the stack trace of the way they are called- open styleguidist and look at the console of your browser
Somewhere in your stack should be one of the displayed components. Find a way to avoid this require. If you can't find a way around this require, use a context variable to only load the router when not in styleguidist.
- Install
cross-envpackage- Set a context variable before you launch styleguidist:
cross-env MYSTYLE=true styleguide serve- Use the variable in your code as follows
If your components rely on an icon set such as FontAwesome, you can edit styleguide.config.js to import it:
See template for more details.
If your base components are in one package and the derived components are in another, you will want the documentation to reflect extended components props in the exposed ones.
Say you have a BaseButton.vue in a @scoped/core package that you extend into IconButton.vue in the @scoped/extended package, the BaseButton.vue props are not going to be documented with IconButton.vue. This can be what you want, or you could be missing a lot of props.
Use the validExtends option to allow parsing of extended components in other packages.
# I have multiple components in the same folder what can I do?If multiple documented components live in the same folder, and you are using a ReadMe file to document them, the content of the readme is going to show for every component.
Three solutions are available depending on taste and context.
# the docs blockThe simplest solution is to use the <docs> block instead. It works well with Vetur syntax highlighting and allows you to never forget to update the documentation.
Trade-off: Markdown files can be read without rendering, in Github for example while coding the component itself. Vue files cannot.
# Named readmesUse the name of the component file switching .vue with .md and you can have one documentation file per component in the folder.
Trade-off: When you enter a folder, Github automatically displays the readme file if it exists. The files you would be writing would not be readmes. No automated file would be loaded.
# Remove unwanted documentationsIn the tags of a component, an @example doclet can be specified. It is usually used to tell styleguidist where to find more documentation.
It can also be used with the special value [none]. It will then hide the example file that would normally be associated with the component.
If you hide with @examples [none] all non-main components, the only remaining readme displayed will the main one. We get our readme file back.
Suppose you have an existing Nuxtjs site or are using Nuxtjs as your development environment for your component library. While you could also encourage users to clone your repo and build the docs, it would be nice to integrate them into your existing Nuxtjs site. This is possible (with some caveats).
First you need to determine the route you want your styleguist docs to be at. For example you may want your docs to be at www.mysite.com/docs. If styleguidist was a pure nuxt page, under the Nuxtjs convention, it would be the file pages/docs.vue. So wherever you want your styleguidist documentation to reside you can not have a pages/<dest>.vue file there!
Next you need to set up the generate properties of the nuxt.config.js. If you are deploying on GitLab, it might be something like this:
If you have generated a nuxtjs site before and looked at the output (here under a dir call public) you will see that each pages/<dest>.vue is a sub directory. This is why you can not have your desired location for styleguidest also be a dest.vue file.
Now you will want to update your styleguide.config.js file to point styleguidDir to the nuxt.config.js's generate.dir, e.g. if you wanted the /docs to be where the styleguideist documentation to be and generate.dir='public' then styleguidDir=public/docs.
Then the last thing is to remember the order of operations. First you generate nuxt (npm run generate) and then build your styleguidist docs.
When using displayName, components in the <docs> block must be imported with their displayName instead of their name.
This is not ideal as your examples are not using the real component name.
A way to get around the problem is to create an alias component, with its original name.
Modify the root element as follow:
You can now use <AcAlert /> in <docs> while the left menu displays Alert.
Example:
⚠️ The search menu won't be able to find
AcAlertanymore, as it searches through the page names, thusAlert.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4