starlight-blog

The starlight-blog plugin provides several features for integrating a blog into a Starlight site:

• Navigation: Automatically links to the blog in the header.
• Post Management: Includes a post list with pagination support.
• Authorship: Supports both global and per-post authors.
• Organization: Includes tag support and cover images for posts.
• UI Components: Provides a custom sidebar that can display recent/featured posts and tags.
• Syndication & SEO: Supports RSS feeds and structured data.
• Scalability: Allows for multiple blog instances within a single site.

Starlight Blog computes metrics based on the post content using these rules:

Word Count

• Calculated using the Intl.Segmenter API, which respects the language of the blog post.
• Code blocks are ignored.
• All markup is stripped from the content before calculation.

Reading Time

• Based on an average reading speed of 213 words per minute.
• Image rules (following Medium's logic):
  • 1st image: +12 seconds
  • 2nd image: +11 seconds
  • Subsequent images: Each adds one less second than the previous (until the 10th image).
  • 10th+ images: Each adds 3 seconds.

To enable automatic fallback content (where a user sees a version of a post in a different language if the current language version is missing), you must create equivalent blog posts in all supported languages.

For example, if you have src/content/docs/en/blog/hello.md, you should also create src/content/docs/fr/blog/hello.md (and for any other languages) to ensure the plugin can provide fallback behavior via Starlight's routing.

Starlight Blog is a plugin designed to add blog functionality to an existing Starlight documentation site. To implement a blog, you must follow these core steps:

1. Install the plugin: Follow the specific installation instructions provided in the getting started guide.
2. Configure the plugin: Add the plugin to your astro.config.mjs file to enable its features.
3. Write blog posts: Create blog posts using standard Markdown or MDX, treating them similarly to how you author pages in your documentation.

To avoid repeating author details in every post, you can define them globally in your astro.config.mjs within the starlightBlog configuration object. Each global author is assigned a unique key. If a blog post's frontmatter does not define an author, the plugin will use these global authors. You can also reference these global authors in a post's frontmatter by using their configuration key.

// astro.config.mjs
starlightBlog({
  authors: {
    hideoo: {
      name: 'HiDeoo',
      title: 'Starlight Aficionado',
      picture: '/hideoo.png', // Images in the `public` directory are supported.
      url: 'https://hideoo.dev',
    },
  },
})

The Starlight Blog plugin exposes blog-wide data through Astro.locals. You can use this data in Astro components, MDX pages, or custom pages rendered via the <StarlightPage> component to build custom widgets like recent post lists or author summaries.

Important: If you have configured multiple blog instances, Astro.locals.starlightBlog will not be available and will throw an error. In that case, you must use Astro.locals.starlightBlogs to access data for a specific instance.

---
const { posts, authors } = Astro.locals.starlightBlog
---

<ul>
  {posts.slice(0, 5).map((post) => (
    <li>
      <a href={post.href}>{post.title}</a>
      <em>({post.metrics.words.total} words)</em>
    </li>
  ))}
</ul>

Excerpts are short summaries or previews of blog posts displayed on list pages (blog post list, authors, and tags pages). You can define excerpts using three methods:

1. excerpt frontmatter property: Define a custom string in the post's YAML frontmatter. Supports basic Markdown formatting.
2. Excerpt delimiters: Place a delimiter within the post content. Everything above the delimiter is used as the excerpt.
3. Fallback: If neither of the above is provided, the entire blog post content is used as the excerpt.

The <Preview> component allows you to render a blog post using the same preview layout found on blog listing pages. This is useful for showcasing specific posts within other pages of your site.

To use it, import the component from starlight-blog/ui/Preview.astro and pass a valid post object (of type StarlightBlogPostData) to it.

---
import Preview from 'starlight-blog/ui/Preview.astro'

// Retrieve a post from the local starlightBlog data
const post = Astro.locals.starlightBlog.posts.at(0)
---

{post && <Preview {post} />}