NEXT: Astro Documentation Site

[endigo9740]

[!WARNING] This issue is a work in progress.

As we begin our journey to Skeleton v3, we'll be migrating our documentation from SvelteKit to a new Astro-based solution. This will help enable support for multiple frontend frameworks running in parallel.

• Preview: https://next.skeleton.dev/

Resources:

• Astro: https://astro.build/
• Starlight: https://github.com/withastro/starlight

Dependencies:

• [x] @astrojs/svelte
• [x] @astrojs/react
• [x] Tailwind
• [x] Cloudflare
• [x] Prettier
• [x] MDX
• [x] Expressive Code - for code blocks
• [x] Nanostores / Persistent
• [x] https://lucide.dev/ - for icons
• https://github.com/skeletonlabs/skeleton/issues/2675

Maintainer Requests

The following requests are coming straight from the Skeleton team. These are highly likely be implemented:

NOTE: updates to the homepage will come late in the process, when we have a better idea of features to showcase

• [x] Flatter navigation structure (see proposal below)
• [x] Auto-generate navigation using Astro MDX content collections
• [x] Improved layouts:
  • Floating centered three column structure for inner docs
  • Detailed frontmatter for standard doc pages
  • Quick switch between Svelte/React/etc
• [x] Convert to static or use prefetch
• [x] Investigate i18n support and translations
• [x] Enable Iconify for Svelte/React components (or switch to Font Awesome)
• [x] Add interface for selecting preferred framework (dropdown, etc)
• [x] Implement Lightswitch component
• [x] More emphasis on tutorials and onboarding materials, as well as news and the blog
• [x] https://github.com/skeletonlabs/skeleton/issues/2591
• [ ] Consider using View Translations, which Astro supports
• [ ] Changelog page (reference)
• [ ] Mobile responsive styles and navigation (awaiting Floating UI integration)

Pages:

• [x] Introduction
  • Simpler overall
  • Provide new/updated video links
  • Replace comparisons with "inspired by" section
  • Improve the FAQ
• [x] Installation
  • Recommend utilizing the the CLI for ease of use
  • Create written walkthrough per each supported meta-framework
  • Use a timeline like view 1, 2, 3, etc to indicate steps
  • Emphasize Typescript support
• [x] Dark mode - instructions may differ per meta-framework
• [x] Cookbook - contains "recipes" for combining Tailwind/Skeleton/JS primitives
• [x] 404 Page (reference)

Astro Components:

• [x] Tabs (persisted for framework selection)
• [x] Tailwind dark mode toggle
• [x] Table of Contents

Integration Guides:

• [ ] https://github.com/skeletonlabs/skeleton/issues/1916
• [ ] https://github.com/skeletonlabs/skeleton/issues/2396
• [ ] https://github.com/skeletonlabs/skeleton/issues/2697
• [ ] Handling dark mode toggles; differs per framework/meta-framework

Community Requests

The following requests have come from the community and are under consideration:

• [x] https://github.com/skeletonlabs/skeleton/issues/1852
• [ ] https://github.com/skeletonlabs/skeleton/issues/2107

Bugs and Issues

• ...

Navigation

The following is a proposal that may grow and evolve over time.

(Top Level)

- Introduction
- Installation
- CLI
- Changelog

Design System

- Essentials
- Figma
- Themes
- Colors
- Dark Mode
- Typography
- Spacing
- Presets

Tailwind

- Alerts
- Badges
- (...)

Components

- Accordions
- App Bars
- (...)

Svelte

- Clipboard
- SVG Filters
- Focus Trap

React

- (Providers, Hooks, etc)

Integrations

- Code Blocks
- Popups
- (...)

Resources

- Cookbook
- Contributing
- Sponsorship

Feedback

If you have additional updates or requests for this feature, please do so in the comments section below.

[Hugos68]

To allow both desktop and mobile users to link to headings by clicking on them we could utilize: https://github.com/rehypejs/rehype-autolink-headings

I saw that Astro already ensures id's are present on headings so no need to use rehype-slug

See full convo: https://discord.com/channels/1003691521280856084/1191790107867488316/1205063596829048892

[niktek]

Need to look at using something like w-full on some (all?) of the samples, e.g. Accordion when all items are collapsed:

[endigo9740]

REMINDER: we need to document:

• https://github.com/skeletonlabs/skeleton/pull/2556
• https://github.com/skeletonlabs/skeleton/pull/2541
• New TW plugin extended class: animate-indeterminate on TW Plugin page

This can be handled once this PR is completed and merged: https://github.com/skeletonlabs/skeleton/pull/2561

[Hugos68]

We need to set the site option in the Astro configuration: https://docs.astro.build/en/reference/configuration-reference/#site Astro strongly recommends this for good reasons. This will result in a Sitemap and Canonical URL to be generated which results in better SEO which results in more visitors/easier to find docs.

[endigo9740]

Consider this for i18n translations: https://inlang.com/c/astro

[endigo9740]

Reminder on mobile navigation drawer: https://github.com/skeletonlabs/skeleton/discussions/2681#discussioncomment-9514241

[Sarenor]

We also need to add the requirement of the tailwind forms plugin to the forms & input page