Support for bootstrapping a style guide based on Bootstrap docs

[alejandroiglesias]

Hey folks, I've been working lately on building a style guide for an app that's based on Bootstrap but has custom components as well. I was thinking that it would be great if there's a easy and intuitive way to also bootstrap a configurable style guide on top of Bootstrap docs. That would allow to generate a static style guide based on and extending Bootstrap docs, and letting you also add your custom modules.
Further, it would be great for it to have Huxley (or similar) integration into a Grunt task, so that it also allows you to test your styles for unintentional changes.
I see a good benefit for everyone to promote the use of style guides and visual testing, and have it easily generated, customized and built, and not to be seen as an unaffordable thing. Much like what Bootstrap is giving to everyone, the ability to have a pattern library from day 0 of your project, same to having a style guide and visual testing from day 0 if you want.
I propose myself as the first contributor to that sub-project after learning a bit more about Bootstrap documentation.
Any feedback on this?

[adamwintle]

I'd like to see something like this too, if we can't find a suitable third-party solution then I'm interested in contributing to this idea too.

From a quick Google search I found http://www.monolinea.com/labs/bootstrap-style-guide-boilerplate/ but its not running the latest version of Bootstrap and no code examples.

Making a one-page component guide, which includes the built Bootstrap CSS/JS into the header/footer wouldn't be too hard to make and include in the project. But having something that auto-generates a guide similar to the Bootstrap Docs would be ideal. The first problem I can foresee if how could we auto (or semi-auto) generate the components into the guide?

[alejandroiglesias]

@adamwintle i don't know that project, just looked at their demo page and it's very basic. I was talking about using Bootstrap's doc pages themselves and build on top of that. It wouldn't be a one-page component guide (but that could be configurable?).

The first problem I can foresee if how could we auto (or semi-auto) generate the components into the guide?

If you look at Bootstrap docs, you can see they already have separate HTML pages per component and build their documentation using Jekyll. I've also read that they are using Markdown in newer Bootstrap 4 docs, but just built them and seems that's still using Jekyll. Didn't got into deep with current docs yet, but I was thinking on having similar flexibility like with Bootstrap Less (now Sass, but will keep referring to Less since it's what i most got used to yet) files:

First approach

// Vendor dependencies
@import '../vendor/bootstrap/less/bootstrap.less';

// Custom app stuff
@import 'variables.less';
@import 'buttons.less'; // Bootstrap buttons overrides
@import 'mycomponent.less';

Second approach:

// Vendor dependencies
@import '../vendor/bootstrap/less/alerts.less';
@import '../vendor/bootstrap/less/buttons.less';

// Custom app stuff
@import 'variables.less';
@import 'buttons.less'; // Bootstrap buttons overrides
@import 'mycomponent.less';

When you build that with Grunt you end up with you app styles on top of Bootstrap in the first place and on top of Bootstrap's Alerts and Buttons in the second place (of course for that to work you need to import more Bootstrap files, but it's just a concept). You can even just build Bootstrap docs with what's provided by the project. What i'm thinking is having the same flexibility, in which the same set of markup and scripts is used to build Bootstrap official docs (in theory) but also serve to help you build your style guide with Bootstrap components plus your components without manually copying and changing Bootstrap docs, and getting outdated after updating Bootstrap.

Sample style guide TOC config file:

css:
- ../lib/bootstrap/docs/_includes/css/buttons.html
- ../lib/bootstrap/docs/_includes/css/code.html

components:
- ../lib/bootstrap/docs/_includes/components/alerts.html
- mycomponent.html  --> custom, will be added to the built style guide 
- ../lib/bootstrap/docs/_includes/components/badges.html

(Would also include all layout templates to automatically adjust navigation to show your custom components.)

This is only concept-code, implementation will certainly vary, but i'm opening dialog space for us to think about this.

[mdo]

So you want to dynamically generate a page of only the specific Bootstrap's components' docs you want to include?

[davidjb]

I've been looking at doing what @alejandroiglesias is suggesting -- coupling/closely associating Bootstrap components with documentation to automatically produce a style guide. Being able to specify the components that should feature in the style guide would make it far easier to extend and follow the main documentation, or customise it to hide/focus on certain parts for certain projects. Perhaps this could be determined automatically from what's components are @import'd in SASS.

Some options that might suit are StyleDown (https://github.com/styledown/styledown), which has an example for Bootstrap v3. There's also LivingStyleGuide, with its build integration options, DocumentCSS, Kalei Styleguide, etc. The boilerplate example, as do quite a few other options, requires PHP and a server for templating.

Some more reading material for the enthusiastic:

• https://github.com/davidhund/styleguide-generators
• http://alistapart.com/blog/post/style-guide-generator-roundup
• http://www.smashingmagazine.com/2015/04/an-in-depth-overview-of-living-style-guide-tools/

[alejandroiglesias]

@mdo: The idea basically is having the same Bootstrap docs imported and interleaved with custom docs for custom components and being able to use custom CSS with Bootstrap overrides. It shouldn't be a hassle for the Bootstrap project and at the same time give something valuable for people wanting to adopt not only a pattern library but also a style guide.

@davidjb: I've investigated and even tried automatically generated style guides. They are neat, but require you to adopt a bunch of things and give less flexibility. Finally ended up making something static manually.

But the core point is that what I'm mostly doing for this private style guide is copying Bootstrap docs, make them load our styles with Bootstrap customizations and adding some components to it. This process could be more lean to us and other people wanting to adopt it by making some adjustments and providing the same flexibility the stylesheets have.

[mdo]

You can fork our docs or snag the content from them (with attribution) in whatever way works best for you. v4's docs have content broken apart into smaller pages, so putting that content where you like or adding more to it should be straightforward enough.

I'm not seeing any specific changes we could make here that we haven't yet in v4, so closing out for now. Feel free to continue opening issues or PRs with specific changes that might help if you'd like.

[davidjb]

For anyone following along, I've taken @mdo's suggestion and forked Bootstrap, customising and adding in extra documentation. I had hoped to 'extend' the set of documentation without forking using Jekyll, but Jekyll isn't built for that. Still, it's been straightforward (once you understand the Grunt/Jekyll build and publish process) -- just a case of adding new entries into the navigation YAML file, adding/customising documentation files and rebuilding.

Customising the _config.yml file for Jekyll handles essentially everything else relating to generating/re-hosting documentation at a different host/path. There were a few things that are getbootstrap.com-specific (ads, Google Analytics and triggers) that are hard-coded but they're simple enough to find and adjust/remove.

[alejandroiglesias]

Thanks for your replies (and sorry for the long time). It might be easier in v4 with the new docs, I don't know, would need to give them a try. I'm not currently working on that project anymore, but still looking for ways to improve UI development workflow.
Everyone that has been through that process (like @davidjb) please chime in and share your thoughts/experience.
Cheers!

[davidjb]

@alejandroiglesias It's essentially just as I've said above, taking the docs, using my custom version of Bootstrap, adding new documentation for new components and rewriting bits of existing work. There's been a bit of adjusting the build processes and removing the getbootstrap.com-specific code but nothing so major that it won't be that bad when merging in changes from upstream. Feel free to look through the work at https://github.com/jcu/web-framework/tree/master/docs, rendered docs at https://web.jcu.io/.