Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adds custom styles for <details> and <summary> elements in Markdown content #1735

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

Adds custom styles for <details> and <summary> elements in Markdown content #1735

wants to merge 8 commits into from

Conversation

HiDeoo
Copy link
Member

@HiDeoo HiDeoo commented Apr 10, 2024 •
edited

What kind of changes does this PR include?

  • Changes or translations of Starlight docs site content
  • Changes to Starlight code

Description

This PR adds custom styles for <details> and <summary> elements in Markdown content, adresssing the request in the built-in components discussion.

Preview playground page: https://starlight-git-fork-hideoo-hd-style-details-astrodotbuild.vercel.app/reference/details/

The approach used does not add a new <Details> component but relies on the native <details> and <summary> HTML elements, similar to the Docusaurus approach.

The current design is based on the Astro Docs custom implementation but the implementation is not exactly identical as I noticed a few minor issues while implementing it (some margins inconsistencies and some border being offset by 1px when toggling the details).
This PR also adds support for RTL languages, prefers-reduced-motion and some minor color adjustments to match the Starlight theme.

One point to note is also the usage of <details> in asides, where the styling deviates from Astro Docs as it can lead to some readability issues. I implemented custom variations to address this, but I don't think it looks the best as I did not introduce any new color (which may be needed to make it more appealing) and I'm also not the best when it comes to design decisions.

I reviewed the accessibility of the implementation using this checklist and testing with screen readers but relying on the native elements ensures most of the concerns are addressed out of the box.

Any feedback is welcome!

@vercel Vercel
Copy link

vercel bot commented Apr 10, 2024 •
edited

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name Status Preview Updated (UTC)
starlight ✅ Ready (Inspect) Visit Preview May 3, 2024 3:05pm

@changeset-bot changeset-bot
Copy link

changeset-bot bot commented Apr 10, 2024 •
edited

🦋 Changeset detected

Latest commit: 033ceb5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@astrojs/starlight Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-actions github-actions bot added 📚 docs Documentation website changes 🌟 core Changes to Starlight’s main package labels Apr 10, 2024
@HiDeoo
Copy link
Member Author

HiDeoo commented Apr 11, 2024

Following a Talking and Doc'ing session (April 11, 2024), some very interesting feedback was received from the participants, thank you all for your time and feedback!

One particular piece of feedback from @kevinzunigacuellar was that it may be difficult to follow if a user is still in a <details> or not , specially in nested <details>. Discussions about this included the idea of adding some borders to the <details> to make it more clear. Here are some screenshots of me playing around with the idea, nothing is final of course and the goal is just to discuss the idea.

Borders around all <details>

Personal opinion: I think this adds a lot of visual noise and importance to the <details>.

Borders around all details

Borders only around nested <details>

Borders only around nested details

Slightly dimmed borders around nested <details>

Slightly dimmed borders around nested details

@HiDeoo
Copy link
Member Author

HiDeoo commented Apr 12, 2024 •
edited

Sharing here another great approach to the design by @delucis

image image

The preview is available here: https://starlight-git-chris-details-dabbling-astrodotbuild.vercel.app/reference/details/

An early feedback for this variation is that it may be less obvious that these are clickable without a more involved CTA compared for example to a Google variation:

image0

HiDeoo and others added 4 commits April 22, 2024 10:44
@HiDeoo
Merge branch 'main' into hd-style-details
ade0395 
* main: (32 commits)
  i18n(pt-br): Update `getting-started.mdx` (withastro#1776)
  i18n(es): update `configuration` (withastro#1766)
  [ci] format
  Add TrueCharts to showcases (withastro#1773)
  i18n(zh-cn): Update `sidebar.mdx` (withastro#1761)
  i18n(ko-KR): update `sidebar.mdx` (withastro#1760)
  i18n(fr): update `guides/sidebar` (withastro#1758)
  test: fix Windows path separator test issues (withastro#1759)
  i18n(fr): Update `reference/configuration.mdx` from withastro#1729 (withastro#1757)
  docs: rewrite `guides/sidebar` examples to be more generic (withastro#1751)
  i18n(ja): Update community-content.mdx (withastro#1756)
  i18n(ja): Update configuration.mdx (withastro#1755)
  i18n(zh-cn): Update `configuration.mdx` (withastro#1753)
  i18n(ko-KR): update `configuration.mdx` (withastro#1752)
  docs: add caution about scripts processing when using head config (withastro#1729)
  i18n(es): update `community-content` (withastro#1740)
  i18n(pt-br): Update `resources/community-content.mdx` (withastro#1747)
  format: quick fix
  [ci] format
  [ci] format
  ...
@HiDeoo
chore: add steps component examples
8cbcafc
@HiDeoo @delucis
feat: update design with chris design
f533c8b 
Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>
@HiDeoo
feat: move marker to the left
7f6607a
@HiDeoo
Copy link
Member Author

HiDeoo commented Apr 22, 2024 •
edited

I updated the PR to use Chris's design. I personally prefer it but as it's now part of the history, we can easily switch between the two if ever needed. My main remaining concern may be the visibility of the left border in light mode.

In a separate commit, I also added a suggestion from Sarah to move the marker to the left to emphasize that these are clickable which was one of the main feedback from the previous post. Same, this can be easily reverted now during iterations.

SCR-20240422-kokq

HiDeoo added 3 commits May 3, 2024 16:13
@HiDeoo
Merge branch 'main' into hd-style-details
2567e15 
* main: (60 commits)
  Add type checking job to the CI workflow (withastro#1827)
  [ci] format
  i18n(pt-BR): Update `components.mdx` (withastro#1815)
  [ci] format
  i18n(ru): update translations (withastro#1825)
  i18n(pt-BR): Update `css-and-tailwind.mdx` (withastro#1817)
  i18n(es): updates `pages` (withastro#1823)
  i18n(es): update `i18n` (withastro#1822)
  i18n(es): updates `overrides` (withastro#1820)
  i18n(es): update `guides/components` and add `syncKey` to various pages (withastro#1818)
  [ci] format
  i18n(es): update `community-content` (withastro#1824)
  i18n(es): update `configuration` (withastro#1821)
  i18n(es): update `frontmatter` (withastro#1819)
  i18n(fr): update `guides/pages.mdx` (withastro#1800)
  i18n(fr): update `reference/overrides.md` (withastro#1803)
  i18n(fr): update `reference/frontmatter.md` (withastro#1802)
  i18n(fr): update `reference/configuration.mdx` (withastro#1801)
  i18n(fr): update `guides/i18n.mdx` (withastro#1799)
  i18n(fr): update `guides/components` and add `syncKey` to various pages (withastro#1797)
  ...
@HiDeoo
feat: tweak details border colors
fff72c8
@HiDeoo
fix: long summary marker position
033ceb5
@astrobot-houston
Copy link
Collaborator

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 guides/authoring-content.md Source changed, localizations will be marked as outdated.
en reference/details.mdx Source added, will be tracked.
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
Copy link
Member Author

HiDeoo commented May 3, 2024

Updated the PR and tweaked border colors: the <details> border color is now more "vivid" compared to the one from a blockquote or a <Steps> component to emphasize that it's an interactive element. Hovering and the opened state borders are also more "vivid" now to match this change.

Hovering an opened <details> element will now also change the border color to a different color to still indicate that it's clickable.

And finally, I fixed a marker position issue with long summaries due to MDX wrapping the summary in a <p> tag.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
🌟 core Changes to Starlight’s main package 📚 docs Documentation website changes
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
2 participants
@HiDeoo @astrobot-houston