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:

• @astrojs/svelte
• @astrojs/react
• Tailwind
• Cloudflare
• Prettier
• MDX
• Expressive Code - for code blocks
• Nanostores / Persistent
  
• https://lucide.dev/ - for icons
• NEXT Doc Search #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

• Flatter navigation structure (see proposal below)
• Auto-generate navigation using Astro MDX content collections
• Improved layouts:
  • Floating centered three column structure for inner docs
  • Detailed frontmatter for standard doc pages
  • Quick switch between Svelte/React/etc
• Convert to static or use prefetch
• Investigate i18n support and translations
• Enable Iconify for Svelte/React components (or switch to Font Awesome)
• Add interface for selecting preferred framework (dropdown, etc)
• Implement Lightswitch component
• More emphasis on tutorials and onboarding materials, as well as news and the blog
• Update docs tabs with Skeleton-Next React Tabs #2591
• Tabs (persisted for framework selection)
• Tailwind dark mode toggle
• Table of Contents
• Tailwind Forms integration instructions for Forms & Input section
• Mobile responsive styles and navigation (using Floating UI React)
• Update component templates to include Zag chip link at top
• Introduce "Integrations" section w/ multi-framework support
• Implement Bluesky API for "News" page

Incoming:

• Describe the replacement to v2 enhancements and background styles
• Semantic typography and Custom font integration guides
• Consider using View Translations, which Astro supports
• Changelog page (reference)
• Implement SEO and social metatags

Integration Guides:

• Integration: Floating UI React/Svelte (Popups) #1916
• Integration: Code Blocks #2396
• Integration: Data Visualization #2697
• Handling dark mode toggles; differs per framework/meta-framework

Community Requests

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

• Audit icon support for popular icon libraries (Iconify, etc) #1852
• Provide recommendation for apps using SvelteKit route groups #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

[endigo9740]

REMINDER: we need to document:

• Feat/progress #2556
• NEXT: Svelte Tabs Component #2541
• New TW plugin extended class: animate-indeterminate on TW Plugin page

This can be handled once this PR is completed and merged: #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: #2681 (comment)

[Sarenor]

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

[endigo9740]

Note that I've split the remaining documentation tasks into three smaller tickets to make them easier to manage and implement:

• v3 Docs: Site Design Refresh #3067
• v3 Docs: Content Updates #2900
• v3 Docs: SEO, Open Graph, and Social Assets #3069

Please redirect any follow ups to these tickets.