Skip to content

Latest commit

 

History

History
110 lines (70 loc) · 6.9 KB

README.md

File metadata and controls

110 lines (70 loc) · 6.9 KB
Raw

Table of contents

About

component-controls is a next-generation tool to help create blazing-fast documentation sites for your libraries and components.

Using MDX or javascript to author documentation files, the sites can be generated with highly-optimized site generators as gatsby or nextjs.

Before starting, take a look at our blog post gatsby vs nextjs vs storybook comparison for generating static documentation sites.

Showcase sites

1. documentation

We believe in the practice of dogfooding, thus we have created the full documentation sites for component-controls using - well, component-controls. Everything from blog posts, tutorials, author profiles to auto-generated component documentation, and testing pages.

2. grommet-controls

This site shows how to create documentation for a custom react UI component library

grommet-controls - source

3. theme-ui design system

This site showcases creating documentation sites for third-party libraries, that are installed in the node_modules folder of your project

theme-ui design system - source

4. starter projects

A collection of simple starter projects, showcasing how to create an MDX pure documentation page, and MDX custom documentation page with a component interactive story and, an ESM javascript page that automatically creates component documentation.

built with gatsby - source

built with nextjs - source

built with webpack 4 - source

built with webpack 5 - source

built with storybook 5 - source

built with storybook 6 - source

Motivation

  • Create a components development environment with testing as a first-class feature.
  • Provide out-of-the-box documentation experience with markdown pages for home page, blogging, and general project documentation.
  • Use smart "super-bundlers" (gatsby, nextjs) to build compact and fast documentation sites.
  • Decouple the user interface from the loading of the 'stories' = modular design.
  • Do not modify the source files (both story and component files) at instrumentation-time as much as possible to avoid random build/run-time errors. The exception is only where necessary, ie instrumenting coverage or performance profiling probes.
  • Ability to document "external" component libraries, living in a separate package from the "stories" package.
  • Built-in AST instrumentation module.
  • Create and support open declarative story formats.

Inspiration

Many developments have contributed to the creation of component-controls, a few of them are:

  • storybook is the original component development system that helps teams to design, develop, and test components. The strong support for testing and the creation of an open Component Story Format was an inspiration, as well as the Storybook Addon Knobs for providing configurable component properties.

  • docz has a beautiful architecture and introduced non-proprietary gatsby build engine. This monorepo was also heavily influenced by the docz project repository structure.

  • docusaurus creates very clean and effective UX for documentation websites. Provides excellent options for project blogging, versioning, translation, and algolia-powered search.

  • abstract syntax tree (AST) advancements have been greatly responsible for making possible the parsing and analysis features of this library.

  • theme-ui is the driving force for standardizing react theming and design systems. theme-ui is used by our project as the theming and components founding block.

  • mdx is driving the adoption of JSX in Markdown and allows writing rich, interactive documentation pages.

Roadmap

  • Core packages
  • Support ESM and MDX stories format
  • Instrumentation packages
  • UI Libraries
  • Storybook integration with addon-docs
  • Storybook integration without addon-docs (replace all storybook loaders)
  • Standalone webpack compiler API
  • HMR
  • Gatsby standalone app/static app builder
  • Nextjs standalone app/static app builder
  • Integrated testing facilites
  • Design tokens componnets to document design systems
  • Support frontmatter MDX declarations
  • Multiple frameworks support (Vue, Angular, tbd)
  • Coverage and performance profiling instrumentation