Skip to content

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

Closed
Closed
Better sidebar markup: distinguish content with and without sub sections.#1181
Labels
PoC welcomeenhancementneeds discussion

Description

@trusktr
trusktr
opened on May 17, 2020

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):

current-sidebar

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?

Activity

  1. trusktr
    added
    enhancement
    feature request
    Need discussion
    PoC welcome
    on May 17, 2020

  2. jhildenbiddle commented on May 17, 2020

    @jhildenbiddle
    jhildenbiddle
    on May 17, 2020
    Member

    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.

  3. trusktr commented on May 18, 2020

    @trusktr
    trusktr
    on May 18, 2020
    MemberAuthor

    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.

  4. trusktr commented on May 18, 2020

    @trusktr
    trusktr
    on May 18, 2020
    MemberAuthor

    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.

  5. trusktr
    changed the title [-]Better markup: distinguish content with and without sub sections.[/-] [+]Better sidebar markup: distinguish content with and without sub sections.[/+] on May 18, 2020

  6. anikethsaha commented on May 18, 2020

    @anikethsaha
    anikethsaha
    on May 18, 2020
    Member

    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 ?

  7. trusktr commented on May 20, 2020

    @trusktr
    trusktr
    on May 20, 2020
    MemberAuthor

    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!).

  8. vagra commented on May 27, 2020

    @vagra
    vagra
    on May 27, 2020
    Contributor

    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.

  9. vagra commented on May 27, 2020

    @vagra
    vagra
    on May 27, 2020
    Contributor

    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);
}

  10. vagra commented on May 27, 2020

    @vagra
    vagra
    on May 27, 2020
    Contributor

    hello.

    I make some changes for sidebar item:
    #1200

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

  11. jhildenbiddle
    added
    needs discussion
    and removed
    feature request
    Need discussion
    on Jul 3, 2020

  12. jhildenbiddle commented on Jul 19, 2024

    @jhildenbiddle
    jhildenbiddle
    on Jul 19, 2024
    Member

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

  13. jhildenbiddle
    closed this as completedon Jul 19, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    PoC welcomeenhancementneeds discussion

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions