Comments (17)
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.
from hologram.
@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.
from hologram.
@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?
from hologram.
@aflanagan this works - thanks!
from hologram.
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
- Buttons
- Components
- Action Bar
- Checklist
- Notifications
- Modules
- Header
- Navigation
Get what I mean?
from hologram.
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?
from hologram.
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:
- Elements
- Components
- Modules
- 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.
from hologram.
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.
from hologram.
@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!
from hologram.
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.
from hologram.
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?
from hologram.
Oh wait, I see what you mean, yeah, hologram doesn't do that.
from hologram.
@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?
from hologram.
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 (-:
from hologram.
@jdcantrell that's great, thanks for the link! We'll try it out and ping you if we run into blockers.
from hologram.
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.
from hologram.
Closing this for now, it's not something I want to add in, but would be open for more discussion and code later.
from hologram.
Related Issues (20)
- Auto-generated nested navigation HOT 3
- `get_binding` error HOT 8
- Markdown not being parsed HOT 2
- How to doc colors HOT 3
- Link external files into HTML-example area? HOT 1
- Multiple styleguides for different sections? HOT 2
- Create new categories with .md files HOT 2
- How would you support multiple languages?
- Ignore subdirectories or specific file
- Can we access markdown variables inside a template? HOT 1
- `ignore_paths` causing error
- SCSS variables and mixins seem to be ignored HOT 1
- Annoying <p class="styleguide"> generated listing CSS styles commented HOT 1
- Seperate JSON file output
- Possible issue with latest rouge update HOT 1
- Primary menu is not useful in its current state
- Provide a means to set order to nav and section items
- haml rendering without code block output
- Still maintained? HOT 4
- Loop in the Markdown HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from hologram.