Better sidebar markup: distinguish content with and without sub sections.

[trusktr]

I've been working on my site, gathering ideas.

Feature request

Improvement of markup so that we know if a menu item will have sub-menu items.

What problem does this feature solve?

Currently, Docsify assumes that every top-level menu item must have sub-content, so therefore docsify-themeable styles the meny items with the open/close icons. There's no way for docsify-themeable to know if a menu item should not be open/close-able.

What does the proposed API look like?

Somehow, the markup should convey whether the menu items will be collapsible or not. This would perhaps add classes in the markup.

How should this be implemented in your opinion?

There's no way for the client-side engine to know ahead of time whether a page will have sub-sections, or not.

Perhaps the only way to do this currently, would be to provide a configuration option, like

window.$docsify = {
  nonCollapsibleMenuItems: [
    './foo/m.md',
    'google.com',
  ]
}

Or maybe, we can expand on the sidebar markdown parser to detect a certain syntax (like Docsify does with other links) to tell it which ones are not collapsible:

- [Foo](./foo.md ':no-collapse') 

I think I like the markdown idea more.

This is what my sidebar markdown looks like:

-   **Guide**

    -   [Install](/install.md)
    -   [Workflows](/workflows.md)

-   **Examples**

    -   [Hello 3D](/examples/hello3d.md)
    -   [Hello 3D, Parent Transforms](/examples/hello3d-parent-transforms.md)
    -   [Ripple flip](/examples/ripple-flip.md)
    -   [Autolayout (declarative)](/examples/autolayout-declarative.md)
    -   [Autolayout (imperative)](/examples/autolayout-imperative.md)
    -   [Morphing spiral](/examples/spiral.md)
    -   [obj-model](/examples/obj-model.md)
    -   [Buttons with shadow](/examples/buttons-with-shadow.md)
    -   [material-texture](/examples/material-texture.md)
    -   [Origin](/examples/origin.md)

-   **API Reference**
    <!-- __API_AUTOGENERATED_BEGIN__ -->
  - components/
    - [Cube](/api/components/Cube.md)
  - core/
    - [ImperativeBase](/api/core/ImperativeBase.md)
    - [Node](/api/core/Node.md)
    - [TreeNode](/api/core/TreeNode.md)
  - html/
    - [WithUpdate](/api/html/WithUpdate.md)

<!-- __API_AUTOGENERATED_END__ -->

And this is currently what it looks like (work in progress):

The items under Examples are all non-collapsible, so I'd like to remove the collapse icons from those. They are the docsify-themeable icons (@jhildenbiddle).

What are your thoughts on how to handle this?

[jhildenbiddle]

Makes sense.

Instead of specifying the collapsable yes/no, perhaps we should allow people to specify the number of sub levels a menu link should display (similar to the subMaxLevel, but that is a global setting for all sidebar links). Setting something like :sub-level=0 would be the equivalent and setting :no-collapse, while setting it a number greater than 0 would limit the sub levels rendered when the sidebar section is expanded to that number.

[trusktr]

Yeah, I think some sort of helper would make sense, especially since Docsify currently can't tell.

For now, I may be able to workaround the issue by setting a class , like [Foo](./foo.md ':class=remove-chevron'). I'm gonna give this a shot.

[trusktr]

Hmm, actually that's not working for me, [Foo](./foo.md ':class=remove-chevron') results in an <a> tag with no class="" applied to it in both the sidebar and main content area.

EDIT, I tried it even with Docsify's example, ![logo](https://docsify.js.org/_media/icon.svg ':class=someCssClass'), but even that doesn't work.

I'm think this is a regression.

[anikethsaha]

I like the :sub-level option as this can give more details.

Hmm, actually that's not working for me, [Foo](./foo.md ':class=remove-chevron') results in an <a> tag with no class="" applied to it in both the sidebar and main content area.

I think this feature is not available for sidebars,

@trusktr this will be for v5 right ?

[trusktr]

I think this feature is not available for sidebars,

True, as most features operate on the content area only. However with this particular feature, I tried it in my markdown pages, and also could not get it to work there. It might be a bug.

Sidenote, I'm cleaning up my branch; I will separate the changes into separate PRs for eaasier discussion, then go from there (finally!).

[vagra]

see my demo site: https://kepan.org/alpha/#/kepan/

is it you want?

source code: https://github.com/vagra/docsify/tree/sidebar

it has other features such as:

• click +/- button to expand/collopse item;
• auto expand/collopse items when scroll;

if you only want the markup should convey whether the menu items will be collapsible or not, it's simple.

[vagra]

I write has-children class for li in tpl.js:

export function tree(toc, tpl = '<ul class="app-sub-sidebar">{inner}</ul>') {
  if (!toc || !toc.length) {
    return '';
  }

  let innerHTML = '';
  toc.forEach(node => {
    if (node.children) {
      innerHTML += `<li class="has-children">`;
      innerHTML += `<a class="section-link" href="${node.slug}">${node.title}</a>`;
      innerHTML += tree(node.children, tpl);
      innerHTML += `</li>`;
    } else {
      innerHTML += `<li><a class="section-link" href="${node.slug}">${node.title}</a></li>`;
    }
  });
  return tpl.replace('{inner}', innerHTML);
}

[vagra]

hello.

I make some changes for sidebar item: https://github.com/docsifyjs/docsify/issues/1200

but it only change icons and add expand/collpse function for app-sub-sidebar, not for sidebar-nav.

[jhildenbiddle]

This issue has been addressed by PR #2469. The changes will be available when Docsify v5 is released.