Allow greater level of category nesting

[VinSpee]

I'd love to be able to nest categories further. ex:

├── elements
│   ├── _forms.sass
│   ├── _lists.sass
│   ├── _loader.sass
│   ├── _tables.sass
│   ├── buttons
│   │   ├── _button.sass
│   │   ├── _close-button.sass
│   │   ├── _minor-button.sass
│   │   └── _save-button.sass
│   ├── forms
│   │   ├── _input-labels.sass
│   │   └── _text-inputs.sass
│   ├── lists
│   │   ├── _bare-list.sass
│   │   ├── _line-list.sass
│   │   ├── _list.sass
│   │   └── _tabs.sass
│   └── text
│       ├── _copy.sass
│       └── _headlines.sass
├── helpers
│   ├── _formatters.sass
│   └── _helpers.sass

that way I can arrange by type, in this case:

• elements
• components
• modules
• helpers

[jdcantrell]

I think we support this nesting already, though perhaps it's not clear in our documentation.
All items under elements would have category: elements and things that are further nested would specify a parent (ie _button.sass would have name: buttons and _close-button.sass would have parent: buttons)

With name and parent you can also nest even more if desired.

[VinSpee]

@jdcantrell as far as I can tell what actually happens is that children inherit the category of their parent. No way to nest categories, unless I'm missing something.

current setup:

├── elements
│   ├── buttons
│   │   ├── _button.sass - name: button; category: elements;
│   │   ├── _close-button.sass - parent: button;
│   │   ├── _minor-button.sass - parent: button;
│   │   └── _save-button.sass - parent: button;

this results in all of the buttons being inside of the "elements" category. I would like to see them in a "buttons" category which is nested inside of the "elements" category.

[aflanagan]

@VinSpee there is currently no way to nest categories at all. However, you could create a top level comment block with the name buttons (category = elements) and then just nest all your different button types below that.

I did this in several places in the Trulia styleguide where the top level comment has no code examples. It's just some text describing the component and a place to setup this type of nesting.

Does that make sense?

[VinSpee]

@aflanagan this works - thanks!

[VinSpee]

actually I'm going to leave this open. While that is a solution @aflanagan, I still think it'd be valuable to be able to nest. For example, I like to follow a sort of combination of SMACSS and Atomic Design. I'd love to be able to nest like so:

• Elements
  • Buttons
    • Base
    • Minor
    • Close
    • Save
  • Inputs
    • text
    • number
    • radio
    • checkbox
    • select
    • multiselect
• Components
  • Action Bar
  • Checklist
  • Notifications
• Modules
  • Header
  • Navigation

Get what I mean?

[aflanagan]

Hmmm...i'm not sure I do. When I look at this structure it looks very similar to how we laid out the Trulia styleguide using the method I described. What is missing that would prevent you from doing this right now?

[VinSpee]

Here's what my desire as applied to the trulia example would look like:

The goal is this: I want to have several categories of documented code:

1. Elements
2. Components
3. Modules
4. Pages

Elements are just that, elements. Components are groups of elements. Modules are groups of components. Pages are groups of modules.

There are many different (and unrelated) types of "elements". Buttons (a parent) and inputs (a parent) are the clearest examples. The reason Hologram in it's current state doesn't quite cut it for this is because they will always be displayed together (on the same page). Ideally, buttons would we a sub-category of elements, and therefore displayed on their own page.

For example, I currently have this setup:

//doc
  ---
  title: Forms
  name: forms
  category: Elements
  ---
  Forms are what the app is really all about.

now, forms has several children:

//doc
  ---
  title: Input Labels
  name: input-labels
  parent: forms
  ---

  Labels describe what you're expecting a user to give you. They should always
  be followed by an input.

//doc
  ---
  title: Text Inputs
  name: text-inputs
  parent: forms
  ---

  Inputs are editable fields that users can put data into. They should always
  have a placeholder, label, and validation.

etc.

I also have buttons, which are a type of element.

//doc
  ---
  title: Buttons
  name: button
  category: Elements
  ---
  Buttons are where the action happens.

which also have several children.

//doc
  ---
  title: Base Button
  name: base-button
  parent: button
  ---
  Re-usable button elements with action specific variants.

//doc
  ---
  title: Minor Button
  name: minor-button
  parent: base-button
  ---
  Minor buttons are used for secondary actions that you don't want the user to necessarily draw attention to.

etc.

Currently, these all show up under the "elements" page. I'd like the elements page to show the content for "name: button" and "name: forms", as well as links to pages that show all of their children. Make sense?

From what I gather, there is no way to do this in Hologram at the time.

[mikezx6r]

I'd agree that this isn't available out of the box with Hologram and given your example, I also support having something like this.

In the meantime, you may be able to hack around to accomplish something very close.

If you give a 'child' element a category different from its parent, it will render on a separate page. To generate your index, you'd have to create categories with 'keys' in them, and in the _header do some custom Ruby.

So, a category like Buttons, and then the child could be 'Buttons > Base'. An example theme that does something along these lines is available at https://github.com/Yago31/Cortana.

It's obviously a fair bit of work, and I'm not completely sure you can achieve what you're looking for, but I think you can get very close.

[VinSpee]

@mikezx6r thank you for the resource and confirmation. Cortana does give me enough to hack around this - thanks so much for that link! I think it would be great to implement something like this at the base level as well. Thanks again!

[jho406]

OooOoo, I like Cortana's category syntax. With that, we can have the parent implied. Its great for documentation since we don't have to jump around files to figure out whats a parent of what and its more informative when you just want to browse around the source code.

[stubbornella]

So cool that people are building themes for hologram. :)

Tonight I worked on a modification to hologram that would allow a component to be listed under multiple Categories. We are using the categories more like filters than a classification system. For example we have base components, form inputs, components that require JavaScript, etc... For us this is helpful because we want to have an "all components" page as well as having the same component listed as requiring JS, for example.

@VinSpee - I think you could have achieved what you are looking for by modifying the navigational markup in _header, but it's great that Cortana gave you what you want. It looks like you wanted level one and two html linked together and level 3 html outputted separately, no?

[stubbornella]

Oh wait, I see what you mean, yeah, hologram doesn't do that.

[gpleiss]

@ckundo, @stubbornella and I would also benefit from nested categories. We want to use a visual diff tool -- like phantomcss or csscritic -- for regression testing. Both tools recommend components on individual pages. Having nested categories would make this possible.

Would you be open to pull requests?

[jdcantrell]

Definitely open to PRs for this, but for your specific task I recently added plugin support to help handle the csscritic case (we're attempting to use it at Trulia as well.)

I made a plugin that will either take html from a test block or from an html_example block and generate a smaller html fragment that can be used for visual testing.

You can see the plugin class and the corresponding doc block to use it here: https://gist.github.com/jdcantrell/b0ad9a6bcbfc2551713f

If this sounds like it might work for you I'm happy to discuss it more via chat/email or some other means (-:

[ckundo]

@jdcantrell that's great, thanks for the link! We'll try it out and ping you if we run into blockers.

[jdcantrell]

This might be helpful: #121. I think my todo list for the next few weeks just became document hologram better. But please let me know if you run in to anything.

[jdcantrell]

Closing this for now, it's not something I want to add in, but would be open for more discussion and code later.