https://github.com/mattrothenberg/vue-elucidate
A library for documenting Vue components
https://github.com/mattrothenberg/vue-elucidate
design design-systems styleguide vue vuejs
Last synced: 7 months ago
JSON representation
A library for documenting Vue components
- Host: GitHub
- URL: https://github.com/mattrothenberg/vue-elucidate
- Owner: mattrothenberg
- License: mit
- Created: 2017-09-26T19:06:48.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2017-10-16T18:11:36.000Z (about 8 years ago)
- Last Synced: 2024-11-07T15:03:36.107Z (about 1 year ago)
- Topics: design, design-systems, styleguide, vue, vuejs
- Language: Vue
- Homepage: https://mattrothenberg.github.io/vue-elucidate-example
- Size: 415 KB
- Stars: 34
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-vue - vue-elucidate - A library for documenting Vue components ` 📝 4 years ago` (Dev Tools [🔝](#readme))
- awesome-vue-zh - Vue阐明 - 为您的生活指南/设计系统生成漂亮文档的组件. (叫研发工具组 / 文档)
- awesome-vue - vue-elucidate - A component that generates beautiful documentation for your living styleguide / design system. (Components & Libraries / Dev Tools)
- awesome-vue - vue-elucidate ★26 - A component that generates beautiful documentation for your living styleguide / design system. (Dev Tools / Docs)
- awesome-vue - vue-elucidate - A component that generates beautiful documentation for your living styleguide / design system. (Dev Tools / Docs)
README
# Elucidate
[](https://badge.fury.io/js/vue-elucidate)
A library that makes it a breeze to "shed light" on your Vue component.
Demo: https://mattrothenberg.github.io/vue-elucidate-example
Demo Video: https://streamable.com/eir1u
# Installation (Yarn)
```
yarn add vue-elucidate
```
# Installation (in a Vue project)
```js
import Elucidate from 'vue-elucidate'
Vue.use(Elucidate)
```
# Usage
```html
```
The `` component takes two props, `component` and `example`.
The former is, quite literally, a single Vue component (either imported into your current app, or defined inline), or an array of Vue components.
The latter is either a single example object shaped thusly, or an array of example objects shaped thusly:
| Key | Value |
| --- | --- |
| `markup` | An HTML code snippet that you would like to document |
| `props` | An object defining the props referenced by your HTML code snippet |
| `methods` | An object defining the methods referenced by your HTML code snippet |
| `name` | (OPTIONAL) A display name for the given component if part of an array of examples |
# How does it work?
Let's assume you have a component named `custom-button`. It's defined in `custom-button.vue` thusly:
```vue
export default {
name: 'custom-button',
props: {
variant: {
type: String,
default: 'primary'
},
size: {
type: String,
default: 'medium'
}
},
computed: {
classList () {
return `btn-${this.variant} btn-${this.size}`
}
}
}
.btn-primary {
background: blue;
color: white;
}
.btn-small {
font-size: 12px;
}
```
Elucidate works by:
- Rendering an example code snippet, e.g., `Hello`
- Documenting that snippet, as well as any props/functions that were passed to it
- Documenting all of the props exposed by ``, in this case `variant` and `size`.
So, the following code:
```html
```
```js
import CustomButton from '@/components/CustomButton'
import '@/darcula.css'
export default {
data () {
return {
button: CustomButton,
example: {
markup: `Hello`
}
}
}
}
```
...would produce the following result:
# Customization
Elucidate is very customizable. I've included some light CSS here and there to make things look half-way decent. Here are a few guidelines for customization.
## BYOCSS
Elucidate uses [Prism JS](http://prismjs.com/) for syntax highlighting. Elucidate doesn't ship out-of-the-box with a particular syntax highlighting theme, so feel free to pick one from [Prism Themes](https://github.com/PrismJS/prism-themes/)
## Default CSS
Include Elucidate's default styles by including the following line of code in your project:
```
import 'vue-elucidate/dist/style.css'
```
Elucidate maintains a light footprint, and affords you the following classes for purposes of customization:
```css
.elucidate-example-picker {}
.elucidate-example-picker label {}
.elucidate-select {}
.elucidate-select select {}
.elucidate-select::after {}
@supports (-webkit-appearance: none) or (appearance: none) or ((-moz-appearance: none) and (mask-type: alpha)) {
.elucidate-select::after {
}
.elucidate-select select {}
.elucidate-select select:focus {}
}
.elucidate-preview {}
.elucidate-tabs {}
.elucidate-tabs .nav-tabs {}
.elucidate-tabs .tab {}
.elucidate-tabs .tab:hover {}
.elucidate-tabs .tab.active {}
.elucidate-tabs .tab:not(:last-of-type) {}
.elucidate-tabs .tab a {}
.elucidate-table-wrap {}
.elucidate-table {}
.elucidate-table th {}
.elucidate-table td {}
```
# To-Do
- [ ] Test Coverage
- [x] Accommodate multiple components in a single example
- [x] Accommodate multiple examples
- [ ] Investigate slot-based API for further customization of sub-components