Website: improvement

[gretanausedaite]

Issue to track some improvements needed in website:

• Short description of components needs to be updated. No more than 3 lines without the concat.
• Split index.astro code into more components. Right now it's a mess with everything in one place and a lot of repetitive code.
• Add version note somewhere in docs.
• Move card/tiles to React component (for better polymorphism support)
• Add a "See also"/"Related" section with links to the related components (comment) website: Add related components section #1185
• Ability to highlight specific lines in code blocks. Maybe using expressive-code.
• Fix sitemap
• Add FAQ (from our wiki)
• Add search functionality: Added Algolia Docsearch to docs website #1365
• Add theme switcher to examples
• Add "related content" to docs pages
• Collapsable side nav areas
• Document exported util functions, components and hooks
• Scrollbar looks wider than in css/storybook examples
• Home screen example be clickable website: Link to components in home page demo #1191
• Add link to Figma component library. website: Update getting started documentation & demos #1358
• Mention browser targets. (comment)
• Props table styling messed up (comment)
• Missing Props tables for sub components (example: tabs only lists props for the legacy api)
• Add a basic usage under each (or most) "Usage" sections on the docs site. E.g. Input, ToggleSwitch, Breadcrumbs. (#1999 (comment))
• Maybe document how users can extend our theme colors to match their color theme. E.g. how to change their accent color but keep all other colors the same, etc.

Far future:

• Guide pages (short "tutorials" how to do things)

[mayank99]

Reposting #1088 (comment) here for visibility:

I'm a bit worried these code samples takes too much space in docs (eg. alert). Especially if only one prop value is changing.

Yeah.. I alluded to this earlier - we should find a way to highlight a single line of code, and describe that the prop can be adjusted. Also, we don't need to show every single permutation and not everything needs a full example, so we should find a way to show only demo or only code instead of always showing both.

I've also been thinking about reorganizing the pages so that examples, writing, and props table live in separate tabs within the same page. This will especially come in handy for bigger components (e.g. Table) which need lots of written documentation but also need lots of examples.

[FlyersPh9]

I explored an alternative design in #1166 for the code samples that take up a little less vertical space. Leaving this here if we decide to revisit the topic.

[mayank99]

We need to improve onboarding. Currently this page is not descriptive enough: https://itwinui.bentley.com/docs

We need to be able to hand people a single link to our website and it should tell them almost everything they need to know and be the central point of linking to other pages (explaining architecture, theming, package names, v2 storybook, old v1 storybook, migration guide, wiki, etc).