Allow set open/expanded state for nested items in routes

[Triex]

I can't seem to find a way to easily set the expanded state as default for nested menu items without forcing it using CSS - which also causes issues. I want to use them as titles.

Is there a workaround for this, or can it be included in an update?

(Also the ability to add links to the menu - which should be excluded from the prev-next buttons - would be pretty amazing ✌️)

Great framework, such minimal. 👌

[maxmilton]

Good idea. Defaulting to an expanded state is a common feature which I considered implementing but didn't have a need for personally. Added in https://github.com/maxmilton/microdoc/pull/305.

About skipping over items in the PrevNext plugin, I'm less convinced about that. What is the specific use case? Could you please open a new issue about that?

[maxmilton]

The expanded feature was published in https://github.com/maxmilton/microdoc/releases/tag/v0.3.3.

The docs were updated too: https://microdoc.js.org/#/configuration.md#routes

[maxmilton]

If you wanted to add an external link to the end of your menu, you can do it like this:

index.html:

<script>
  function ready(fn){"loading"!==document.readyState?fn():document.addEventListener("DOMContentLoaded",fn)}

  ready(()=>{
    const link = microdoc.h('<li><a href="https://example.com" class="microdoc-sidenav-item">Example Link</a></li>');
    document.querySelector(".microdoc-sidenav-list").append(link);
  })
</script>

The h function comes from my https://github.com/maxmilton/stage1 framework which is what powers microdoc under the hood. It's undocumented, however it's a fork of https://github.com/Freak613/stage0, which does have some simple documentation. The basics here are simple enough to understand; it takes a string of HTML and turns it into a real HTML DOM with a reference to the root element in the string (the <li> in this case).

If that's not the kind of thing you were after let me know.

[Triex]

That is perfect, the example and detailed response is super useful, thank you very much! 🙏

May potentially be worth adding that link append example to the docs for newbs. Or allowing you to enter a URL instead of an .md link. If not complicating it too much.

I've now opened an issue explaining a use case for the prevnext suggestion.

[maxmilton]

My current thinking around external links is they don't belong in the sidenav. Ideally the sidenav should be just content menu items. That way the UX is consistent and predictable. All the best project documentation sites I use as a reference all follow the same pattern.

If there were an external link in the sidenav it would need some special indication it's external. Wikipedia for example does a good job at this. You could include a ↗️ character at the end of the route name as a simple way to achieve this.

However, it's so easy to add links in content, so why not do that?

Maybe use a custom footer is you have heaps of links.

Where there's a very important external link that you always want to show (e.g., a link to a project's Github page), then that should probably be in the top header area. That's a feature we don't currently have but which I've been meaning to implement.

I've also been considering allowing for separate major sections, each with their own submenu:

├── guide
│  ├── faq.md
│  └── introduction.md
├── api
│  ├── api-page1.md
│  └── api-page2.md
├── tutorials
│  └── how-to-x.md
└── [github link]

However I'm still on the fence about that. I need to give it some more thought and create a new issue.

[maxmilton]

As generic solution for styling external links, you could plop something like this into your index.html:

<style>
  /* External links */
  a:not([href*='#']):not([href='/']) {
    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20' fill='%235c7080'%3E%3Cpath d='M11 3a1 1 0 1 0 0 2h2.586l-6.293 6.293a1 1 0 1 0 1.414 1.414L15 6.414V9a1 1 0 1 0 2 0V4a1 1 0 0 0-1-1h-5z'/%3E%3Cpath d='M5 5a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h8a2 2 0 0 0 2-2v-3a1 1 0 1 0-2 0v3H5V7h3a1 1 0 0 0 0-2H5z'/%3E%3C/svg%3E");
    background-repeat: no-repeat;
    background-position: right;
    padding-right: 1.1em;
  }
</style>