Generating "submenu" from markdown headings in CSS

[aripalo]

Currently StyleDocco lists the different stylesheet files in the left side navigation.

Could it be possible to generate "submenu" / childmenu after the stylesheet name, that would contain hierarchical list of markdown headings inside the stylesheet and have links to them?

Example, I could have following CSS:

/* 
Typography
==========
Here are global typography styles etc
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
*/

/* 
Headings
--------
  <h1>heading 1</h1>
  <h2>heading 2</h2>
*/
h1, h2 { /* ... */ }

/* 
Links
-----
  <a href="#example">Default link style</a>
*/
a:link, a:visited { /* ... */ }
a:active, a:hover { /* ... */ }

/* 
containers
==========
Here are styles for the different containers.
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
*/

/* 
Main
----
*/
.main { /* ... */ }

/* 
Sidebar
-------
*/
.sidebar { /* ... */ }

... and it would convert to a menu that would be something like this in the styleguide left side nav:

stylesheet.css
├── Typography
│   ├── Headings
│   └── Links
└── Containers
    ├── Main
    └── Sidebar

Then these menuitems would link to matching section in the styleguide.

[jacobrask]

I've thought a bit about this lately too actually.

In v0.5 there will be a top bar instead of the sidebar, with dropdown menus, to allow the previews to be wider, for new responsive debugging features.

My idea was to put a search bar next to the dropdown menus, which would search both the module (file) names as well as the section headings, with direct links in an autocomplete popup thing. Would that solve your use case as well?

[aripalo]

Well that would help of course, but I feel a list - a "sitemap" or "cataloque" in a way - would be still needed. Since in team project some back-end people might want to look around the docs/styleguide without knowing what is available.

I might have an idea about this, since you brought up the idea of using top bar instead of sidebar. I could do some really quick wireframes later tonight or tomorrow and show what I have in mind.

[aripalo]

... and the hierarchical list would help to perceive/understand how the stylesheet has been structured.

But the search-field with autocomplete is a good idea, which definitely should be there! :)

[jacobrask]

I've pushed the new topbar + a bunch of other stuff to github so you can see it, but I haven't released it to npm yet, still some things to fix.

I'd love to see your idea visualized!

[redonkulus]

+1 to this idea as well. Ideally the headers would just become a table of contents at the top of the file. I find myself doing this manually in my CSS files:

/**

Table of Contents:

• Non-semantic helper classes
• Pre-defined Font Sizes
• Arrow button styles
• Progress Bar
• Loading
• Logos
• Buttons
• Tabs
• Switches
• Dialogs
• Lists
• [Headers][(#section-13) */

[redonkulus]

For what its worth, I created a super simple script to generate the TOC based on the H1's on the page. All you need to do it put the following gist in the docs.js file and then put a <div id="toc"></div> somewhere in the page:

https://gist.github.com/3176259

[jacobrask]

Fixed, but the design is not "hierarchical", it simply lists all headings level 1-3 in the current document. I will revisit that later.