Components documentation improvements #2121

HiDeoo · 2024-07-10T12:31:27Z

Description

Closes Starlight components documentation improvements #1938 and Export Component type to user #2010

This PR is a follow-up of #1938 to improve the components documentation and move away from the single page currently used.

This pull request is a draft as it only includes a global component guide and the new references for the <Tabs> and <Badge> components. The idea is to first get feedback on the new format, discuss remaining questions and then continue with the rest of the components once the format is agreed upon.

The <Badge> page was chosen as it's relatively simple and small while the <Tabs> page was chosen as it's a more complex one which involves 2 components.

To give a brief overview of some of the changes per page:

Global Components Guide

This is pretty much the introduction of the current Components guide.
It also includes a new section for ComponentProps to address Export Component type to user #2010.

Component References

The global structure is as follows:

Brief description of the component
Preview of the component in a basic example with no code example
Import statement
A usage section with various use cases
- Each usage includes a code example and the associated preview
A props section with a list of all accepted props
- A link to the component implementation (can be useful to see where/how extra props are spread for example)
- This follow the pattern used in other references

Some other notes:

Links exists between props mentioned in the usage section and the props section ~~and vice versa~~ (decided that it was not useful after discussing this).
In the props section, the required tag is not included in the title (this allows for switching languages without losing position compared to the other reference pages).
The component used to display code examples and/or previews is pretty much unstyled at this point of the PR:
- The idea of the component is to make the examples more obvious with some kind of frame around it compared to the current examples.
- We would need to decide if we want some controls on it or keep it as simple as possible:
  - I think one important thing to consider is that Starlight is not a component library/design system
  - Most examples researched include a "Show Code" / "Open in StackBlitz" button which I don't think are relevant for Starlight as we want to show both the code and the preview at the same time.
  - One of the controls I think could be relevant would be a toggle to switch the preview between light and dark mode although this one could be tricky to implement with Starlight's current code.
- Do we want to keep the duplicated content in the markup (for the code and preview) like we currently have or do we want to have a more advanced setup, maybe relying on remark, to only have to specify the code once?
  - Not sure this is worth it considering the number of components and the complexity it could add

Remaining tasks

Once the format is agreed upon, convert the rest of the components to the new format
Use a custom UI string for the "Preview" word
- Wait for Use i18next for UI strings and add new injectTranslations plugin callback #1923 to be merged
Remove the existing components guide
Add a redirect for the old guide (/guides/components/)
Figure out where the new references should live in the sidebar (I used a top-level group for now to make it easier to find)
Make sure to merge with the Lunaria tracker directive from this comment

changeset-bot · 2024-07-10T12:31:31Z

⚠️ No Changeset found

Latest commit: 1f61a1c

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 · 2024-07-10T12:31:57Z

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	`1f61a1c`
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/66ea8c4b3065fd0008a41a2d
😎 Deploy Preview	https://deploy-preview-2121--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 100 (no change from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: - View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify site configuration.

astrobot-houston · 2024-07-10T12:32:04Z

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale	File	Note
en	components/asides.mdx	Source added, will be tracked.
en	components/badges.mdx	Source added, will be tracked.
en	components/card-grids.mdx	Source added, will be tracked.
en	components/cards.mdx	Source added, will be tracked.
en	components/code.mdx	Source added, will be tracked.
en	components/file-tree.mdx	Source added, will be tracked.
en	components/icons.mdx	Source added, will be tracked.
en	components/link-buttons.mdx	Source added, will be tracked.
en	components/link-cards.mdx	Source added, will be tracked.
en	components/steps.mdx	Source added, will be tracked.
en	components/tabs.mdx	Source added, will be tracked.
en	components/using-components.mdx	Source added, will be tracked.
de	guides/components.mdx	Localization removed, will be marked as missing. 🔄️
es	getting-started.mdx	Localization changed, will be marked as complete.
es	guides/components.mdx	Localization removed, will be marked as missing. 🔄️
fr	getting-started.mdx	Localization changed, will be marked as complete.
fr	guides/components.mdx	Localization removed, will be marked as missing. 🔄️
en	getting-started.mdx	Source changed, localizations will be marked as outdated.
en	guides/components.mdx	Source removed, will stop being tracked.
hi	getting-started.mdx	Localization changed, will be marked as complete.
hi	guides/components.mdx	Localization removed, will be marked as missing. 🔄️
id	getting-started.mdx	Localization changed, will be marked as complete.
id	guides/components.mdx	Localization removed, will be marked as missing. 🔄️
it	getting-started.mdx	Localization changed, will be marked as complete.
it	guides/components.mdx	Localization removed, will be marked as missing. 🔄️
ja	getting-started.mdx	Localization changed, will be marked as complete.
ja	guides/components.mdx	Localization removed, will be marked as missing. 🔄️
ko	getting-started.mdx	Localization changed, will be marked as complete.
ko	guides/components.mdx	Localization removed, will be marked as missing. 🔄️
pt-br	getting-started.mdx	Localization changed, will be marked as complete.
pt-br	guides/components.mdx	Localization removed, will be marked as missing. 🔄️
pt-pt	getting-started.mdx	Localization changed, will be marked as complete.
en	reference/icons.mdx	Source added, will be tracked.
ru	getting-started.mdx	Localization changed, will be marked as complete.
ru	guides/components.mdx	Localization removed, will be marked as missing. 🔄️
tr	getting-started.mdx	Localization changed, will be marked as complete.
tr	guides/components.mdx	Localization removed, will be marked as missing. 🔄️
uk	getting-started.mdx	Localization changed, will be marked as complete.
zh-cn	getting-started.mdx	Localization changed, will be marked as complete.
zh-cn	guides/components.mdx	Localization removed, will be marked as missing. 🔄️

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

HiDeoo · 2024-08-02T15:52:34Z

Updated the pull request, here is a summary of the changes:

Updated the existing page structure based on feedback gathered during Talking & Doc'ing and some other discussions.
Added new component pages for all existing Starlight components
- One potential area I'm not really sure about is the <Card>, <LinkCard>, and <CardGrid> components, which are now 3 different pages. I think it makes sense as <CardGrid> can be used with both and we probably don't want to duplicate the information in both the <Card> and <LinkCard> pages. But I'm open to feedback on this.
- Still related to these 3 pages, I grouped them in the sidebar so they're next to each others. May also need some changes if we decide to use another approach.
Added a new reference page for icons (based on Sarah's idea)
- As icons are not always used with <Icon> but can be used a prop in other components, or even frontmatter values, the icons list is now a separate reference page.
- Searching using the browser's search feature is more reliable as the page mostly consists of icon names.
- As the idea is that icons are not only tied to the <Icon> component, clicking on an icon will now copy the icon name to the clipboard and not the entire <Icon> component with the icon name. (this has probably been one of my most annoying issues with the current implementation, I always want the name, never the icon. It makes testing different icons a pain as you have to replace the entire <Icon> component with your new clipboard value, and if your <Icon> use any extra prop, e.g. size, you cannot easily paste at all)
- I tried implementing in this page an icon categorization based on Unicons category (as we discussed here), but reverted the change as I don't think it's a good solution at the moment. As we only have a small selection of icons from the Unicons library, we can end up with some categories with only one icon. I think we should wait until we embed the full Unicons library or use astro-icon to use a categorization based on categories.

* main: (121 commits) i18n(zh-cn): Update components.mdx (withastro#2240) i18n(zh-cn): Update frontmatter.mdx (withastro#2239) i18n(zh-cn): Update pages.mdx (withastro#2238) i18n(zh-cn): Add synced tabs persistence (withastro#2236) Update examples index hero button action variants (withastro#2234) i18n(fr): update `guides/components` (withastro#2232) i18n(fr): update `guides/pages` (withastro#2224) [i18nIgnore] docs: update `index.mdx` hero action buttons variants (withastro#2233) i18n(fr): update `reference/frontmatter` (withastro#2223) i18n(fr): update `index` (withastro#2222) docs: add Cloudflare Docs to showcase (withastro#2221) i18n(ko-KR): update `pages.mdx` (withastro#2227) i18n(ko-KR): update `components.mdx` (withastro#2225) i18n(ko-KR): update `fontmatter.md` (withastro#2231) i18n(ko-KR): update `manual-setup.mdx` (withastro#2230) [ci] format i18n(ko-KR): update `index.mdx` (withastro#2229) i18n(ko-KR): update `site-search.mdx` (withastro#2228) i18n(ko-KR): update `customization.mdx` (withastro#2226) i18n(fr): add missing `syncKey` to various pages (withastro#2218) ...

HiDeoo · 2024-08-19T13:40:47Z

Updated the PR with the changes of #2087 & #1784.

HiDeoo · 2024-09-06T12:57:44Z

In anticipation of #2249, I updated the PR with Markdoc support:

Added a script to generate Markdoc grammar from the one in their own LSP server repo and configured the documentation to use it (markdoc language identifier)
Updated the "Using components" page to mention Markdoc (it's the one I am the most unsure about)
Updated all component pages to also include Markdoc examples (basic <Tabs> at the moment, maybe need to refine the UI a bit)
- The only example not having a Markdoc equivalent is the "Use imported code" one as I don't think it's doable.
- Formatting wise, I used the "Format" button on their playground for all examples.

~~Note that the link checker failure is expected as I link to documentation only existing in #2249 at the moment, I'll update the PR once it's merged to fix the issues.~~

* main: (37 commits) [ci] format i18n(ko-KR): update `manual-setup.mdx` (withastro#2294) i18n(ko-KR): update `configuration.mdx` (withastro#2295) [ci] release (withastro#2292) Add support for SSR (withastro#1255) Add Markdoc preset and example (withastro#2249) Refactor sidebar persistence logic for better slow device performance (withastro#2242) [ci] format Add docs.ryzekit.com to showcase (withastro#2291) Update astro dependency to 4.15.3 across monorepo (withastro#2289) [ci] release (withastro#2290) Prevent Zod errors from crashing build (withastro#2288) i18n(fr): update `guides/css-and-tailwind` (withastro#2286) i18n(ko-KR): update `css-and-tailwind.mdx` (withastro#2284) Add WCAG AAA colour contrast option to theme editor (withastro#2282) [ci] release (withastro#2283) Parse `<StarlightPage />` frontmatter asynchronously (withastro#2279) Ensure unhandled directives are restored without any extra whitespace (withastro#2281) i18n(fr): update `resources/plugins` (withastro#2278) i18n(ko-KR): update `plugins.mdx` (withastro#2277) ...

docs/src/content/docs/components/using-components.mdx

docs/src/content/docs/components/card-grids.mdx

Co-authored-by: Sarah Rainsberger <[email protected]>

delucis

Awesome work on this @HiDeoo! From the nice new preview pane design to the careful work structuring these pages in a consistent way that is flexible across all the different components we have, this is lightyears ahead of where we were. Stellar work 💖

HiDeoo added 3 commits July 10, 2024 11:37

docs: add using components guide

277bcd6

docs: add tabs component reference

968077b

docs: add badge component reference

c9dacee

This comment was marked as outdated.

Sign in to view

github-actions bot added the 📚 docs Documentation website changes label Jul 10, 2024

vercel bot deployed to Preview – starlight July 10, 2024 12:32 View deployment

HiDeoo added 11 commits August 2, 2024 17:44

docs: update badge component reference

36021e8

docs: update tabs component reference

4d23e0c

docs: add asides component reference

d8bd18d

docs: add cards component reference

35e1fa8

docs: add link cards component reference

2dd642b

docs: add card grids component reference

61f14b5

docs: add code component reference

0c4fbe8

docs: add file tree component reference

5034465

docs: add steps component reference

e9a94ac

docs: add icons component reference

67144f6

docs: add icons reference page

3229ea6

HiDeoo added 3 commits August 19, 2024 14:55

docs: update tabs syncKey with persistence

93d24be

docs: add link button component reference

96d398b

delucis mentioned this pull request Aug 30, 2024

Add Markdoc preset and example #2249

Merged

11 tasks

HiDeoo added 2 commits September 6, 2024 14:38

docs: add markdoc grammar

c75bc4d

docs: add markdoc examples

1b3e216

docs: delete old components guide translations

d4fd0b3

sarah11918 reviewed Sep 17, 2024

View reviewed changes

docs/src/content/docs/components/using-components.mdx Outdated Show resolved Hide resolved

sarah11918 reviewed Sep 17, 2024

View reviewed changes

docs/src/content/docs/components/card-grids.mdx Outdated Show resolved Hide resolved

HiDeoo and others added 5 commits September 17, 2024 15:04

fix: example highlighted lines

c15c7fe

Co-authored-by: Sarah Rainsberger <[email protected]>

docs: tweak available components sidebar sentence

a870d0f

Co-authored-by: Sarah Rainsberger <[email protected]>

Merge branch 'main' into hd-feat-docs-components

087b09f

feat: add component.preview ui label

bedbc1c

Merge branch 'main' into hd-feat-docs-components

1873562

delucis approved these changes Sep 18, 2024

View reviewed changes

Merge branch 'main' into hd-feat-docs-components

1f61a1c

HiDeoo merged commit 41ed4fa into withastro:main Sep 18, 2024
16 checks passed

HiDeoo deleted the hd-feat-docs-components branch September 18, 2024 08:20

This was referenced Oct 8, 2024

i18n(zh-cn): add link-buttons.mdx #2445

Merged

i18n(zh-cn): add steps.mdx #2446

Merged

i18n(zh-cn): add tabs.mdx & update astro.config.mjs #2456

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Components documentation improvements #2121

Components documentation improvements #2121

HiDeoo commented Jul 10, 2024 •

edited

Loading

changeset-bot bot commented Jul 10, 2024 •

edited

Loading

This comment was marked as outdated.

netlify bot commented Jul 10, 2024 •

edited

Loading

astrobot-houston commented Jul 10, 2024 •

edited

Loading

HiDeoo commented Aug 2, 2024 •

edited

Loading

HiDeoo commented Aug 19, 2024

HiDeoo commented Sep 6, 2024 •

edited

Loading

delucis left a comment

Components documentation improvements #2121

Components documentation improvements #2121

Conversation

HiDeoo commented Jul 10, 2024 • edited Loading

Description

Global Components Guide

Component References

Remaining tasks

changeset-bot bot commented Jul 10, 2024 • edited Loading

⚠️ No Changeset found

This comment was marked as outdated.

netlify bot commented Jul 10, 2024 • edited Loading

✅ Deploy Preview for astro-starlight ready!

astrobot-houston commented Jul 10, 2024 • edited Loading

Lunaria Status Overview

Tracked Files

HiDeoo commented Aug 2, 2024 • edited Loading

HiDeoo commented Aug 19, 2024

HiDeoo commented Sep 6, 2024 • edited Loading

delucis left a comment

Choose a reason for hiding this comment

HiDeoo commented Jul 10, 2024 •

edited

Loading

changeset-bot bot commented Jul 10, 2024 •

edited

Loading

netlify bot commented Jul 10, 2024 •

edited

Loading

astrobot-houston commented Jul 10, 2024 •

edited

Loading

HiDeoo commented Aug 2, 2024 •

edited

Loading

HiDeoo commented Sep 6, 2024 •

edited

Loading