"Your docs are so great that I want a build of them w/ my theme" tips

Hi all:

For better or worse, I have a project that combines:

• some selectively exported SUIR components, &
• some custom inhouse components

I’m after the holy grail.

• i need my UX team engaged in Code Reviews, so we use storybook’s awesome service to deploy a static website on each commit, w/ all of our UI widgets on display
• i need documentation for my inhouse components & want a widget playground for my custom components, so we integrate a styleguidist frame into our storybook
• more importantly, i want to be able to see & get rolling updates of your great work in SUIR with my theme applied over it!

right now, I just iframe over to your docs, as seen above. it’s a total hack.

because semantic themes have other assets beyond CSS, I can’t just mess w/ the frame & inject my theme over it.

im brainstorming some ways to achieve my goal. the goal is, get SUIR docs to render my custom theme. i could:

1. clone suir, install deps, squash your assets, build
   1. it intensive, slow, and arguably fragile
2. extract docs out of this package, into semantic-ui-react-docs. this exports an executable & a lib to control the build
   1. node_modules/.bin/suir-docs --assets <my-asset-dir> -o <my-dest>
   2. const suirDocs = require('suir-docs'); suriDocs.build(config)
   3. this is invasive to the project, & i’d imagine you all wouldn’t be nuts about it. regardless, it could be pretty cool! it would shrink this project up!
3. add some hooks into the docs website that enables me to swap assets
   1. using postMessage the CSS could likely easily be swapped if in an iframe. not sure about handling images/fonts, but they could possibly be Blobable and passed thru messaging.
4. <other-ideas-here>

anyway, thx for reading this far! i appreciate your time. great work!

[cdaringe]

thanks @agustif. i did end up finding an OK solution. i do a SUI theme build, & pull in the theme into a react-styleguidist build. we went styleguidist because our lib takes SUIR + theme-overrides as input, and provides SUIR & our own additional components as output, thus wanted the documentation engine that storybook just doesn’t quite yet have yet. here’s a ref. the caveat to our strategy is that we dont get all of SUIR examples which help make this project so great, and have to manually backfill them!

i also wrote a little package, surge-review, that makes the workflow really great. once our CI builds the docs site on each pull request, surge-review posts the static build to surge (CDN), and then updates our PRs with a link the the documentation build. woo hoo 🎉

[levithomason]

This is great. We’re doing a lot of work in the new https://github.com/stardust-ui/react repo around themes and docs. We want to share that experience here in Semantic UI as well. It will also likely be used by another large open source repo and some corporate private repos.

All said, we want to start modularizing our doc experience and sharing features between Stardust and Semantic. Stardust supports TypeScript, CSS in JS, and has a “Transparent” background feature. Semantic has better code completions, Prettier integration, and runs Babel. I’d like to merge all these things into a single clean experience that people can install and use in their own project.

I’d like to publish this doc experience from Stardust UI. A good start would be cleanup and separate the concerns of each component used in the doc experience.