Add navbar icon support via new config item

[choldgraf]

This is WIP because I think it needs a change in mystmd to work.

It lets users define icon links for their navigation bar, like so:

site:
  options:
    navbar_icons:
      - icon: github
        url: https://github.com/...

I gave a shot at implementing navigation bar icon links, but I think I ran into a blocker. It doesn't seem like the navbar link configuration is being passed through in the build - I think because mystmd isn't handling them. I think what needs to happen is the following change in mystmd:

Add support for array option types in template validation - I wanted to let users pass a list of icon types, but I don't think there's any list-like site option supported. Here's where I was looking:

https://github.com/jupyter-book/mystmd/blob/506cdce0851031991f49718e2653cf2f21ff6676/packages/myst-common/src/templates.ts#L8-L14

and it seems like this is where the check happens for option types:

https://github.com/jupyter-book/mystmd/blob/506cdce0851031991f49718e2653cf2f21ff6676/packages/myst-templates/src/validators.ts#L92-L105

If that is indeed the blocker, LMK and I can either try to figure that out, or take other direction if I'm going about this wrong. It feels reasonable to support both arrays and dictionaries. If others agree I can write up an issue.

Alternative implementation

An alternative approach would be to support parts-like functionality for the navbar, and then add a role that would output an icon link. For example, something like the sidebar footer, e.g.:

site:
  parts:
    navbar_right: {icon}`github <any-url>` | {icon}`repo` which would try to pull from project metadata

something like that, though the specifics of the roles UX would need to be improved there

---

• closes Support for icon links for social, github, external links, etc in the theme header #362
• closes Support Gitlab repo for link mystmd#2697

[changeset-bot]

⚠️ No Changeset found

Latest commit: d12499f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[netlify]

❌ Deploy Preview for myst-theme failed. Why did it fail? →

Name	Link
🔨 Latest commit	d12499f
🔍 Latest deploy log	https://app.netlify.com/projects/myst-theme/deploys/698b60d07ea94d0008ac3525

[agoose77]

This is way too short -- I'm in the collab cafe.

Rather than defining a theme-specific config here, the high level plan around this was to define these kinds of links in existing frontmatter (which we do support), and use a different mechanism to link them into the footer (e.g. via a special placeholder node) or the nav bar through theme-config.

I think this PR might overlap — we define the social links in the frontmatter already in mystmd, and then use something like the ID pattern for authors (where we have contributors defined in a contributors.yml file, and reference them by ID in single douments) to pull the specific icons into the navbar. Let's talk about this? I think @stefanv also would be interested

[choldgraf]

@agoose77 I think it would be pretty easy to piggy-back on the social media metadata in this PR if we wanted. e.g. why not also support a pattern like:

navbar_icons:
  - social: github

and this would look up the social metadata instead of letting a person provide their own URL/icon.

The main change we'd need in mystmd right now is to allow arrays/lists in the site.options so that you can list multiple icons to include in the navbar (since users may want to configure this independently).

Are you thinking about doing something more similar to parts so that this is a more re-usable pattern? e.g.:

navbar_extra: navbar.md

with like:

navbar.md

{icons}`github,url,github[url=foo.com]`

?

[choldgraf]

Here's another issue that would be resolved by this one:

• Support Gitlab repo for link mystmd#2697

It feels like we are preventing incremental progress on waiting for a perfect solution here. Is there a way we can implement this functionality without closing any major architectural doors that we'd regret later to make this feel less risky to @agoose77 ?

[rowanc1]

I don't think we have a type array?

Similar to the nav this is a special property that this PR is introducing across all site themes.

[choldgraf]

Yeah I think this part needs to be changed to object or something - I haven't put any cycles in this since my original push because it's not clear to me if folks want to make a deeper change in mystmd first and it's blocking this

[choldgraf]

Yeah I think this part needs to be changed to object or something - I haven't put any cycles in this since my original push because it's not clear to me if folks want to make a deeper change in mystmd first and it's blocking this

[rowanc1]

Do you think we could do this with parts instead?

I don't think the current solution validates the navbar_icons array in any way. And the links could be added as a part, similar to the existing way to pass in the bottom of the nav?

[choldgraf]

We'd need to add parts support to the navbar in that case (similar to the sidebar footer). If folks are +1 on that I don't think the implementation would be too hard. In that case we could start with something that gets rendered after the dark theme logo and has whatever parsed myst you provided in the part, maybe with some special roles for icon links

(Also just to be clear don't take the current implementation as ready to merge - once I get clarity about what we want from a design perspective then I can add extra testing validation etc if need be)

[choldgraf]

I updated the top comment with an alternative implementation pathway - if that's preferable to @rowanc1 or @agoose77 I can open up another PR that takes that approach instead. It shouldn't be too complex given that we use this pattern in many other places. A benefit of this is that you'd be able to re-use the same icon roles for the footer, sidebar, etc as you wish.

[rowanc1]

I do think that going in a parts direction is a better/more-general approach. If a site template doesn't implement that part - it is fine. This also could be picked up in a typst theme - and can still have @agoose77's approach of a custom role in the future ({social-links}`linkedin,github,discord` or similar, making it easier to get access from config -> custom role -> content part -> rendered part).

This also means we could have that part rendered in the nav bar right, or in the table of contents top/bottom (we already have a toc bottom area I think). And that would be a single part-name-change to put the content in a different place. I like that a lot.

There is also #752 which adds icons. That could potentially be merged first? Then the parts would be even easier as the logos/links would already be there (or inline images/svgs etc because it is content).

[choldgraf]

Closing this because we went with parts!