Explore adding top-level "API" link to header nav

[bvaughn]

This discussion thread on Twitter provided feedback that the reference section of the docs may not be very discoverable due to the new website's accordion sidebar.

@gaearon proposed we could do something similar to what Jest does and add an "API" link to the header that directly opens the first page of the reference section (eg React Top-Level API).

Unfortunately this is a little more complicated than it would seem at a glance because of:

• How we determine which header link gets the "active" style. If we added a new "API" link, both it and "Docs" would share the same "/docs" URL path. (Jest side-steps this issue by not applying "active" header link styles.)
• We try to maintain symmetry between the location of markdown content (eg content/blog, content/docs) and the top-level nav structure (eg "Blog", "Docs")

Unfortunately we can't rely on anything dynamic (like markdown frontmatter tags) to help with the "active" link styling because the header and footer are part of the "static" Gatsby layout. (Technically we could move them into the templates but this doesn't seem ideal.)

We could move reference docs into a new folder (eg "content/api") give them a unique URL prefix (eg "/api") but we'd need to leave backwards-compatible redirects (eg redirect_from like here) in place so that no bookmarked links were broken. This would also require separating "Docs" and "API" sidebar structure.

[KyleAMathews]

You could just make the active style programmatic right? Just say any reference doc pages make the API header link active.

Perhaps removing the accordion is an option too?

[bvaughn]

You could just make the active style programmatic right? Just say any reference doc pages make the API header link active.

We could but that's what this section from the description was referencing:

Unfortunately we can't rely on anything dynamic (like markdown frontmatter tags) to help with the "active" link styling because the header and footer are part of the "static" Gatsby layout. (Technically we could move them into the templates but this doesn't seem ideal.)

Short of moving the header out of the layout or hard-coding a bunch of URLs in it- how would you propose we do this?

[KyleAMathews]

hard-coding a bunch of URLs

done! https://github.com/reactjs/reactjs.org/blob/master/content/docs/nav.yml :-)

[bvaughn]

Reading between the lines, what you're suggesting seems a bit janky to me.

It would require us to embed nav YML files in the layout component (rather than their template) and do pattern matching based on file names / slugs (which might cause conflicts between top-level docs folders) rather than the root of the URL.

I guess we could combine both techniques (root of the URL + filename) but I still don't like the nav YMLs being used in the layout.

[KyleAMathews]

Yeah, you'd import the docs yaml file into the layout component and there, check the current pathname against the list of paths in the yaml file. If the path is in the reference section, you highlight "API".

[bvaughn]

Sure, I understand what you're proposing 😄 it just seems janky to me.

[KyleAMathews]

Give it five minutes Brian! ;-)

[jxom]

@bvaughn @KyleAMathews - what if a content/api folder (and hence an 'API' nav item) is added, whereby the 'Reference' content in content/docs is moved to this new content/api folder. And perhaps the Docs page could reference the content in content/api for the 'Reference' section? Could do this by content/docs/nav.yml referencing content/api/nav.yml somehow? That's my two cents. 🤷‍♀️ Hope it makes sense! (that rhymes 😎)

[bvaughn]

Hey @jxom! 😄

That's mostly what I was referring to in the last paragraph of the description, except that I would not want to combine navs in that case- to avoid introducing complexity (for people contributing code, for future changes we might make to the nav bar, etc.)

Of the options that I've listed and/or that have been discussed so far, I do prefer a new, separate /content/api folder. (That is, if we do this at all.)