Generated Index Component #965
Replies: 10 comments
-
Definitely confusing ^^ (at least for me). Just to be sure, we are talking about generating a page looking something like this one, correct? If that is the case, I think I personally do not have the use case so I may be wrong but wouldn't we also need sidebar group labels to be real links to these pages for the feature to be easy to use? Also random thought but I may be again totally off, but could this works like Starlight |
Beta Was this translation helpful? Give feedback.
-
Maybe we could call it "Generated Index" for discussion sake to at least make it more clear in this context? Updated the issue title and an edit in the original issue.
Yup! Screenshot for reference just so it's easier for others to follow:
I think I understand what you're asking but I could be wrong. Are you talking about how you would represent an entry like the outlined one in this screenshot:
It very well could be exposed as an option there. My initial reaction is I really appreciate having access to these components so I can have the flexibility to slot them wherever I like on the page so I think I'd still like it being an exported component. But it could be useful to add it as an option for that layout. (hit the enter button by mistake, so content is edited) |
Beta Was this translation helpful? Give feedback.
-
I like it ^^ And thanks for the screenshot.
Yeah, definitely, I would assume that if I generate an index for my "guides" section, clicking on "Guides" in the sidebar would navigate to it, kinda like in Docusaurus but this is not possible right now in Starlight afaik. So if this feature ends up being implemented, I would assume this would need to be added as well? And another random idea, I guess this could also fit in the {
label: 'Reference',
autogenerate: { directory: 'reference', index: true },
}, |
Beta Was this translation helpful? Give feedback.
-
Thanks for the issue @lorenzolewis! I can certainly see the benefit of reusing some logic here that makes having this built-in vs in userland a good idea. I’m less convinced by the idea of “automatic” index pages. In particular, we’ve had questions before about making the heading of a sidebar group also a link to the index page, but I think this results in confusing UX. Docusaurus does this and you essentially end up with an entry that does different things depending where you click on it:
I don’t think that behaviour is clear at all to users and would prefer to avoid it. I’d suggest making this a standalone component for now that you can drop into any page with some config to determine where it auto-generates from. Another reference for this general concept where a single link in the sidebar contains a navigation component for subpages can be found in Astro’s docs on pages like this: https://docs.astro.build/en/guides/migrate-to-astro/ |
Beta Was this translation helpful? Give feedback.
-
I agree about confession around something being a sidebar group title vs. a link, so I'd be on board with keeping auto-generated index pages out of scope for now (although I do see it as a valid use case, just a more tricky on to have good UX around). @delucis do you have any wisdom on what type of API/types to expose for this? If you think it'd be confusing DX to name/build things off the sidebar logic since this isn't technically a sidebar? I could imagine a component that looks like this: import { Index } from '@astrojs/starlight/components';
<Index directory="guides" /> that builds out all of the pages under I haven't dug into the sidebar logic code to see how easy it would be to build off of it yet, figured I'd better get a thumbs-up on that approach first. |
Beta Was this translation helpful? Give feedback.
-
Best to design your ideal API first and then we can see if it’s feasible! Looks like Docusaurus’s component actually has no props, always showing the parent directory’s pages. I generally prefer explicit over implicit and think you might want to show e.g. a child directory’s pages just as often, so something like I’d also say for now this could be limited specifically to autogenerated groups because arguably, using Maybe you want to look at the various |
Beta Was this translation helpful? Give feedback.
-
Awesome! I created a non-parameterised version of this over the weekend for Tauri so should give me a good starting point to work on a PR this week for some initial feedback. |
Beta Was this translation helpful? Give feedback.
-
Put in #513 as the first stab at this one. |
Beta Was this translation helpful? Give feedback.
-
I have a version of this that is entirely in user space. |
Beta Was this translation helpful? Give feedback.
-
I use it with the index pages that only kind of sort of work while waiting for #370 to be fixed. |
Beta Was this translation helpful? Give feedback.
-
What version of
starlight
are you using?0.7.0
What is your idea?
Create a user-facing component that behaves similarly to how sidebar objects work, but instead being listed in the content of a page.
The name "Table of Contents" could be confusing since technically that already exists on the trailing side of the page, so open to workshopping the name. (edit: revising to be "Generated Index" just to make it less confusing to talk through).
This would wrap the new
<LinkCard>
component within a<CardGrid>
and dynamically fill in the contents based on page's frontmatter (title
anddescription
).This could potentially respect the new
sidebar.label
,sidebar.order
. andsidebar.hidden
properties in generation, although this could be confusing due to the values being under thesidebar
name and this not being a sidebar (maybe this could be an opt-in/opt-out behaviour?)The last bit to tackle would be how you specify which content you'd like this component to render. I'm not 100% sure what I would expect this to be but I could think of these options:
SidebarItem
with what you'd like (autogeneration could be very very useful here)src/content/docs/foo
for exampleThe approach I'd prefer is very tightly coupled to the sidebar logic as it would allow us to just build on top of that. However it could be confusing DX to a user when using that outside of the context of the sidebar. So open to any thoughts on this as well.
I'm willing to work on a PR for this one depending on how willing we are to build on top of the sidebar logic. If we want a slightly different path of logic then I might need to step down depending on how complex it would be 😅
Why is this feature necessary?
Sometimes you just want a really nice looking landing page without writing it by hand.
Do you have examples of this feature in other projects?
Docusaurus: https://docusaurus.io/docs/sidebar/items#generated-index-page and https://docusaurus.io/docs/sidebar/items#embedding-generated-index-in-doc-page
Participation
Beta Was this translation helpful? Give feedback.
All reactions