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

[cdaringe]

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!

[levithomason]

TL;DR

Yep. Love this and have thought through all these same things. In fact, I've built a few prototypes as well. Here are my thoughts:

Component Explorer

I do like the docs we have, but, I'd like to have a component explorer more similar to react storybook. See #427 for early prototypes.

The general idea is to give these things simultaneously:

• a single rendered example
• a form for changing component props (generated from the component props)
• a set of predefined examples so choose from
• the same code editor we currently have

How is this different than storybook? The generated form for trying out different component props easily and the code editor to edit the full example live. Essentially, it is more dev friendly. Aside from that, it is obviously completely tailored to our build.

Themes

Yes!

A

I've built an in-browser theme customizer with hot CSS in the past, for bootstrap. The app is old and slow, but you can get the idea here: http://bootstylebeta.herokuapp.com:

B

There is also an in-browser SUI theme toy for the GitHub rebuild example: http://semantic-org.github.io/example-github/

C

Finally, there is the theme selector for many examples in SUI core docs: http://semantic-ui.com/elements/button.html

---

I'd like to allow a way to build and preview themes in the docs, somehow. I've been thinking this might be in the form of a theme customizer tool in the docs as in "A", maybe. At a minimum, a way to select a theme similar to "B" and "C" above.

I've also been thinking perhaps this new method of theming and/or applying themes should also include a better way to theme our own components. You can a lot of my thoughts on that here, #1009.

Lots of ideas and options here, just not yet totally sure which is the best way to go. I do think I want to keep this as a doc site app feature.

[cdaringe]

thanks for the super detailed response!

Component Explorer

yup. its fantastic ™.

Themes

i'm super in favor of a pure, native web-app. however, themes cannot be applied completely in this strategy because non-CSS assets do not have a way of being reliably loaded. we added on some extra fonts & imgs that integrate w/ SUIR components for example, that I consider key to our experience. maybe that's too much to ask to support! regardless, the only way I see my use case working is a means to essentially run a build on your docs w/ my content. a little webservice attached to the webapp could also facilitate that, but bleck, that's a lot of work!

[levithomason]

I see. You could certainly clone our repo and run a build. All scripts are in the package.json. Docs are a fairly straight-forward webpack build, if there is such a thing.

The doc site is a React app that lives in /docs/app. The config is webpack.config.js. The script to build them is npm run build:docs. The built docs are emitted to /docs/dist.

I'm open to ideas and PRs for anything that takes us closer to a themeable doc site. I'll close this issue for now but we can continue the discussion if needed. Thanks for the taking the time to raise these points. I trust we'll get some level of support here in the future one way or another.

[cdaringe]

cool, that's helpful. i may need to automate that in our CI build!

[agustif]

Im sorry If I'm out of topic here.

I did manage to build storybook inside a boilerplate with Phoenix+Webpack2+React+Semantic-UI-React-Semantic-UI-less

I am able to apply modifications on CSS and have it auto-reload with my own theming into semantic-ui-less variables and site overrides

I thought it would be cool to use storybook for semantic-ui with plugins and stuff

anyways @cdaringe lemme know if you're still looking into this!

[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 🎉

[lolero]

I also put together a solution to this problem here and posted a question on stackoverflow in case you want to follow the thread here.

[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.

[lolero]

Thanks for your reply @levithomason!

I had not heard of Stardust UI but it looks great. Is it still a work in progress or are there more components coming to it soon?

Some of the most important reasons why I decided to write the Semantic UI theme builder were

• To provide a centralized place where themes could be developed, versioned, built for production, and pulled from as other project's dependencies
• To provide the Semantic UI docs web app, ready for deployment to a project's hosted domain, themed with the project's themes. The intention is that a project's UI/UX team can review the state of all of the project's themed components, as well as all other available components that have not yet been styled to the projects design specs
• To include an 'Externals' component section in the Semantic UI docs web app so that SUI themes can also include styling for external components such as react-datepicker, react-table, etc. which consume the project's color variables and other common design parameters
• To support the use of third party icon libraries like Font Awesome Free, Font Awesome Pro, etc.

Have you considered these points in the purpose and design of Stardust as well?
It would be excellent if Stardust also addressed these issues :)

[stale]

There has been no activity in this thread for 180 days. While we care about every issue and we’d love to see this fixed, the core team’s time is limited so we have to focus our attention on the issues that are most pressing. Therefore, we will likely not be able to get to this one.

However, PRs for this issue will of course be accepted and welcome!

If there is no more activity in the next 180 days, this issue will be closed automatically for housekeeping. To prevent this, simply leave a reply here. Thanks!

[stale]

This issue will be closed due to lack of activity for 12 months. If you’d like this to be reopened, just leave a comment; we do monitor them!