🗃️ Use and display of `_category_` (folder) metadata

[JFWooten4]

This issue is inspired by remarks at #2411 (comment) stating:

the convention for the repo is front matter sidebar_position only, no _category_.json files.

Copilot disagreed with this assertion when it was added to a PR in progress, at #2579 (comment).

---

I have undergone significant effort to create category files, accepting that they do look a little bit out of place as json files scattered within an mdx repo docs folder. The original PR expanded existing category metadata as file front matter by styling (subfolder) card descriptions. A lot of the docs pages are these kinds of menu arrays listing subdirectories or just contained pages:

Firstly, the intent of the "Open Markdown" was for AI use (implemented in #2289 in conjunction with LLMs.txt changes). #2249 indicated that it was for "making it easy for developers to grab structured content." Directory pages do not generally include such information that may be needed during development flows, and I propose we remove that distracting button on directories.

Secondly, the descriptions imported from child files get only one truncated line, making previews almost unusable. This limitation is particularly bad on mobile:

(It leaves drafters to choose between descriptive page titles or concise descriptions, neither of which properly index informative copy.)

Thirdly, folders within folders do not natively include information. They only list the number of sub-items, unless you add a category JSON file. I believe this looks infinitely better than a bunch of useless item counts across cards.

In my PR where this came up, @Shaptic and @chowbao added some rare descriptive text to the category page in #1785 (review). I then migrated that metadata into the actual folder category JSONs so that it showed up in one uniform place:

(I deprecated the duplication of category titles and later descriptions in #2412.)

---

I would like to have this kind of structured directory metadata throughout the docs, because it makes things much easier to navigate, much less repetitive, and much easier to parse in search and agent workflows. I propose using the category files extensively to add metadata about folders, and even apply custom DocCard emojis to represent their contents. What do you think about a framework for this sort of meta description within the card buttons?

[ElliotFriend]

Hey, @JFWooten4!!

1. agree that the "Open Markdown" doesn't provide much useful info on the category pages. if the plugin gets updated to actually place a list of pages when it's a category, that would probably be useful. but now, that's probably better served as another issue.
2. yeah, the truncated lines are a bit limiting. the best approach to expanding them is probably CSS-related. text--truncate is the only directive that's controlling the size. but, it could very easily lead to mismatching and weird card sizes.
3. you're right about the description being omitted from the README.mdx frontmatter. i thought those descriptions got "hoisted" up from the index page for the category, but i was wrong. the title, sidebar label, sidebar positions, pretty much everything else in the frontmatters ends up applying to the category card, but not the description 🤷🏻‍♂️. there's a relevant, if old, issue on DocCards showing a category which has an associated doc should show that doc's description (used in generated-index) facebook/docusaurus#7598 that's still open. we might want to raise that the issue still exists over there, as well.

you're also right about the note from copilot that there are indeed some _category_.json files scattered throughout the repo. if you look through them, they're used (almost) exclusively for collapsible and collapsed where we're flipping off the default values. there are a lot of reasons i prefer the README.mdx convention over the _category_.json convention, but there are limitations to what's possible without the json file. i think that's really what i'm aiming for when i said "no category json" files. it's more like i want to do as much as possible in the README.mdx files, and fallback to the category json files only when necessary, and for only those necessary things. does that make sense? given what you've pointed out about the third point above, i'd say a category's description can fall into that "necessary things" list.

i'm not so sure about the custom doccard emoji, though, if i'm being honest. feels like it might be opening up a can of worms for not much benefit.

[JFWooten4]

The new refs above do a lot in solving conventions around the third point and what you elaborated on thereafter. And I certainly agree with the approach in the contributing, doing as much as possible in READMEs. In fact, I'm even looking at how we could potentially expand the inbuilt functionality in JFWooten4#32.

That also relates to the first point, which, as laid out, probably needs its own issue. There are a lot of agentic workflow implications for that, and it's not a trivial solution since some pages have manually indexed frontmatter. Tyler was kind enough to comment on the specific uptake methods in #2624 (comment).

I think that leaves this issue squarely at putting together a uniform way to expand the DocCards. My swizzled implementation did this with four lines, which stayed at a constant vertical height no matter the description metadata. Given the outstanding upstream remarks for so long, I think the best course of action is a simplified version of that.

Lastly, I really like the custom emoji for (i) replacing external outbound links with 🔗 (as of now, the cards show them like any normal page) and (ii) replacing whatever this is with something closer to 📂:

[ElliotFriend]

i thought outbound links did have some signifier that they are external? do you have an example of a page on our site that is showing an external link? none are coming to mind for me

the icon you're seeing there is different than any i've ever seen. on my machine it looks like a file cabinet.