From a53bddf8f6383f72bd377c3fbfc9cd36440af226 Mon Sep 17 00:00:00 2001 From: Eric Liu Date: Fri, 27 Nov 2020 05:15:24 -0800 Subject: [PATCH] improve documentation (#424) * chore(deps-dev): pin sveld dependency to v0.3.0 * docs: escape HTML in component prop descriptions * docs(ordered-list): describe use case for using native styles #418 * docs: update count for icons, charts packages * docs(readme): update description, links --- README.md | 18 +++++++++++++++--- docs/src/components/ComponentApi.svelte | 5 ++++- docs/src/pages/components/OrderedList.svx | 2 ++ docs/src/pages/index.svelte | 14 +++++++------- package.json | 2 +- yarn.lock | 2 +- 6 files changed, 30 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index a830cdfd..b84646aa 100644 --- a/README.md +++ b/README.md @@ -5,13 +5,25 @@ ![npm downloads to date](https://img.shields.io/npm/dt/carbon-components-svelte?color=262626&style=for-the-badge) [![Build][build]][build-badge] -carbon-components-svelte is a Svelte component library that implements the [Carbon Design System](https://github.com/carbon-design-system), an open source design system by IBM. +Carbon Components Svelte is a [Svelte](https://github.com/sveltejs/svelte) component library that implements the [Carbon Design System](https://github.com/carbon-design-system), an open source design system by IBM. -A design system can facilitate frontend development and prototyping because it encourages reuse, consistency, and extensibility. +Design systems facilitate design and development through reuse, consistency, and extensibility. + +The Carbon Svelte portfolio also includes: + +- **[Carbon Icons Svelte](https://github.com/IBM/carbon-icons-svelte)**: 5800+ Carbon icons as Svelte components +- **[Carbon Pictograms Svelte](https://github.com/IBM/carbon-pictograms-svelte)**: 600+ Carbon pictograms as Svelte components +- **[Carbon Charts Svelte](https://github.com/carbon-design-system/carbon-charts/tree/master/packages/svelte)**: 16 chart types, powered by d3 ## [Documentation](http://ibm.biz/carbon-svelte) -Deploys by Vercel +Deploys by Vercel + +The [documentation website](http://ibm.biz/carbon-svelte) contains live demos and examples. Other forms of documentation are auto-generated: + +- **[Component Index](COMPONENT_INDEX.md)**: Markdown file documenting component props, slots, and events +- **[TypeScript definitions](types)**: Component TypeScript definitions +- **[Component API](docs/src/COMPONENT_API.json)**: Component API metadata in JSON format ## Getting started diff --git a/docs/src/components/ComponentApi.svelte b/docs/src/components/ComponentApi.svelte index d3b3376a..75356c97 100644 --- a/docs/src/components/ComponentApi.svelte +++ b/docs/src/components/ComponentApi.svelte @@ -138,7 +138,10 @@ {#if prop.description} {#each prop.description.split('\n') as line}
- {@html line.replace(/`(.*?)`/g, '$1')}. + {@html line + .replace(/\/g, '>') + .replace(/`(.*?)`/g, '$1')}.
{/each} {:else} diff --git a/docs/src/pages/components/OrderedList.svx b/docs/src/pages/components/OrderedList.svx index e8275202..58b5bfb6 100644 --- a/docs/src/pages/components/OrderedList.svx +++ b/docs/src/pages/components/OrderedList.svx @@ -51,6 +51,8 @@ components: ["OrderedList", "ListItem"] ### Native list styles +Use the `native` attribute to enable default browser list styles. This is useful for large lists (i.e., 1000 or more items) where the list number may overlap with the list item text. + Ordered list level 1 diff --git a/docs/src/pages/index.svelte b/docs/src/pages/index.svelte index db977621..395a59ed 100644 --- a/docs/src/pages/index.svelte +++ b/docs/src/pages/index.svelte @@ -25,7 +25,7 @@

Carbon Components Svelte

- carbon-components-svelte is a + Carbon Components Svelte is a

- A design system can facilitate frontend development and prototyping - because it encourages reuse, consistency, and extensibility. + Design systems facilitate design and development through reuse, + consistency, and extensibility.

@@ -74,8 +74,8 @@

Portfolio

- The broader Carbon Svelte effort extends to the icons, pictograms, and - data visualization libraries. + The broader Carbon Svelte effort includes libraries for icons, + pictograms, and data visualization.

@@ -94,7 +94,7 @@ @@ -113,7 +113,7 @@ diff --git a/package.json b/package.json index 69742996..ab58a089 100644 --- a/package.json +++ b/package.json @@ -39,7 +39,7 @@ "rollup": "^2.33.3", "rollup-plugin-svelte": "^6.1.1", "rollup-plugin-terser": "^7.0.2", - "sveld": "^0.3.0", + "sveld": "0.3.0", "svelte": "^3.29.7", "svelte-check": "^1.1.15", "svelte-loader": "^2.13.6", diff --git a/yarn.lock b/yarn.lock index f25d9996..cdd0005f 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2728,7 +2728,7 @@ supports-color@^7.0.0, supports-color@^7.1.0: dependencies: has-flag "^4.0.0" -sveld@^0.3.0: +sveld@0.3.0: version "0.3.0" resolved "https://registry.npmjs.org/sveld/-/sveld-0.3.0.tgz#a1a8c188511a8d5674c72fd8b2987278fae0d062" integrity sha512-aEuxRaeN11P+k0DvQ+32lEzRQNzv+dFO5qRC4wSM0p5MW9i6sxgPmnYV3xy5TSzaYXVmSI9JJRSMDd3C1ayw0w==