Cleaner way to define sections

[danielsneijers]

Just thinking aloud here: wouldn't it be much easier to use the folder structure to define sections in the styleguide instead of using globs in the config file? For example, I currently have:

- components
| - ShareButton
| - AcquisitionButton
| - etc

But it'd be great if I could add a section to the sidebar by just grouping these buttons in its own button folder:

- components
| - Buttons
  | - ShareButton
  | - AcquisitionButton
| - etc

Would be happy to draft a PR if this is a viable option

[mik01aj]

Good idea, but how would you specify section titles and additional docs (md) then?

[danielsneijers]

Additional docs could be in the root of the section folder, having a Readme.md in there doesn't hurt. The titles could be more tricky. First instinct is: just go with the folder name, but I'm not sure how messy things could get with spaces in the folder names.

[mik01aj]

Readme.md in folder is a good idea! Github supports this as well.

Maybe the first header in the readme would then also become the section title? Note that it would mean, that if you want the section name to be different than folder name, you have to create a Readme.md just with a header.

[danielsneijers]

Ah so you take the folder name if there's no Readme.md, but otherwise take the first # title of readme and use that as a title, correct? One other thing that pops in my mind: how does the styleguide handle subfolders right now? Because it'd be a challenge to support multiple layers of subfolders for sections. I'm thinking supporting just the first level (maybe recursively add folders below that to the section) would be easiest to present in a visually pleasing way. So in short:

- components
| - Buttons
  | - ShareButton
  | - AcquisitionButton
| - etc

Would render a button section with different components in it, but

- components
| - Buttons
  | - ShareButtons
    | - FacebookButton
    | - TwitterButton
  | - AcquisitionButton
| - etc

Would just render the FacebookButton and TwitterButton in the Buttons section. Don't want to make it too complicated :)

[mik01aj]

how does the styleguide handle subfolders right now?

it doesn't. You just specify globs that find components, and they become a flat list then.

I like the idea of using the folder structure, because this would reduce the amount of configuration needed to start using styleguidist. But if we need some special rules for nested folders, then I'm not so sure anymore.

[danielsneijers]

I think it's best to keep it as simple as possible for the end user, it's totally possible to support multiple levels of subfolders without special rules. The toughest part would be to make it visually pleasing. I'm not that familiar with the source of this project (yet) but I'll try to draft some code and see how it feels, if you're ok with that.

[mik01aj]

I find it ok, but I'd say that currently configuring the cestions is not a problem for me. I have a styleguide with 120 examples, and my sections config is as simple as:

sections: [
    {name: 'Introduction', content: './introduction.md'},
    {name: 'Core UI', components: '../core/[A-Z]*/index.jsx'},
    {name: 'Generic UI & partials', components: '../ui/[A-Z]*/index.jsx'},
    {name: 'Dialogs', components: '../dialogs/[A-Z]*/index.jsx'},
    {name: 'Pages', components: '../pages/[A-Z]*/index.jsx'},
    {name: 'Admin UI', components: '../adminUi/[A-Z]*/index.jsx'},
],

And btw - think also about md-only sections (like the introduction in my case). I don't want to put it in a new folder, so it looks like some config is still unavoidable.

And I'd also suggest that you write some full examples here, I mean: example file structures and the expected output. Then we could refine this before you even start coding. :)

[sapegin]

I like the idea but I’m not sure how to combine in with the current implementation. For example I need some docs as Markdown-only sections (which I want to define in the current style, via config) and components folder (which I want to use the folders detection magic).

Maybe something like hat could work:

sections: [
    {name: 'Introduction', content: './introduction.md'},
    {name: 'Components', components: './components'},  // Just a folder, not glob pattern
],

[danielsneijers]

Hmm it indeed has some edge cases I didn't see before. I'll think about it before working out some examples, maybe some other contributers/community have some good ideas about this.

[danielsneijers]

I did some work on our work in progress styleguide and I have to say: the current way of defining folders works pretty well once you have it in place. In retrospect I think adding the folder method would unnecessarily complicate this project, so unless this is still something you'd like to see in the future you can consider this issue solved.

[sapegin]

@danielsneijers Awesome! If you could share a screenshot of something that would be very cool ;-)