Starlight plugin to add a blog to your documentation
Home Page: https://starlight-blog-docs.vercel.app
License: MIT License
Want to get started immediately? Check out the getting started guide or check out the demo to see the plugin in action.
A Starlight plugin to add a blog to your documentation site.
Licensed under the MIT License, Copyright © HiDeoo.
See LICENSE for more information.
Sort of!
Most of the time, my blog posts include and render Astro components, so the rendering within the RSS feed is not that readable as is:
We can see there for instance a import ProjectThumbnail from '../../../components/ProjectThumbnail.astro' at the beginning of the feed.
It's probably not a common use case for starlight-blog, but I think being able to use another content via the interface could be useful.
I'm thinking about giving the possibility to use the excerpt for instance in the plugin configuration by adding a new parameter. Maybe something like:
starlightBlog({
rss: {
excerptAsContent: true // false by default
}
})
It would be transparent for the majority of users. And folks having complex content to render could use the excerpt to have a text without "embellishments".
Note: If not having the entire blog post in the feed is not a good practice (I'm not used to use them a lot), feel free to close this issue.
I'm not sure if it'd be possible, but another alternative would be to override what's done by default by starlight-blog to create my own RSS "rendering".
No response
Currently the only way of letting readers know that the blog was updated after its creation is the lastUpdated frontmatter, which isn't pretty obvious to find on the bottom of the page.
Some common blog websites have an extra field for the updated date and I think it wouldn't be that hard to integrate a new frontmatter or rewrite the current one with a field displayed next to the creation date for an updated date (not required of course).
A frontmatter prop (like dateUpdated) which displays the date next to the creation date (date frontmatter), so that the reader quickly sees that there have been changes (recently)...
If nobody needs this, than I'll stick to the lastUpdated frontmatter, but still would be happy to some this small feature implemented in some future... (maybe in another universe...)
No response
Whenever using the search, there are duplicate results for blog posts, looks like the search also includes tag pages. Including pagefind: false in the post frontmatter seems to remove a few of the duplicate results, but you also lose being able to search in the specific blog page rather than the entirety of the blog at once
starlight-blogYou can see an example with the starlight-blog docs
It should only display one result, which would preferably be the main blog post. Such as this example (using Docusaurus/Algolia)
Every time
n/a
No response
Summary: Currently, the /blog route generated by the plugin doesn't seem to be supporting an i18n project.
In my project, I have a root locale (fr), and another locale (en) in its own folder, as seen below.
.
├── src/
│ ├── assets/
│ ├── content/
│ │ ├── docs/
│ │ │ ├── en/
│ │ │ │ ├── blog/
│ │ │ │ │ └── first-article.md
│ │ │ │ │ └── second-article.md
│ │ │ │ └── about.mdx
│ │ │ │ └── index.mdx
│ │ │ ├── blog/
│ │ │ │ └── premier-article.md
│ │ │ │ └── deuxieme-article.md
│ │ │ └── a-propos.mdx
│ │ │ └── index.mdx
│ │ └── config.ts
│ └── env.d.ts
├── astro.config.mjs
However, when I try to set up a blog for the other locale (under docs/en/blog) I run into problems.
/en/blog returns 404/en, then navigate to blog => falls back to French /blog/The plug-in should accommodate an i18n setup.
Creating a /blog folder in the different locales folders should generate a blog homepage and link accessible via /locale/blog/
No response
As the plug-in documentation doesn't refer to i18n, I still tried to set up a blog for the other locale (under docs/en/blog), but ran into problems described above.
Thank you for your time.
My website works heavily with sub-domain, so as you can assume, my blog site is my domain with blog in front of it. The /blog that always comes after just looks werid
Maybe make it so that we can set prefix to an empty string, and if it is, then just put everything in root.
I already tried the above solution, and it didn't work. I would also like the /blog page, which shows all the posts to be my main site, that is found when you visit the plain URL of blog..
No response
When using both starlightImageZoom() and starlightBlog() (in that order), they for the most part, work together. However, on the blog post itself, frontmatter such as date/cover/author is not displayed. When using starlightBlog() and starlightImageZoom() (in that order), the frontmatter does show but starlightImageZoom() will not work anymore.
astro.config.mjs, include both plugins in the relevant order inside starlight integration. Should look like this:export default defineConfig({
integrations: [starlight({
plugins: [starlightImageZoom(), starlightBlog()],
// other code unrelatedThe blog function should work, you will be able to see the sidebar change with recent posts, tags, and all posts. However, when clicking on a blog post, the frontmatter such as date/author/cover will not display.
Every time
Operating system: Windows 11 Pro Version 23H2
Browser: Google Chrome version 126.0.6478.127 (Official Build) (64-bit)
Astro version: v4.11.0
---
title: Wazuh + SOAR Implementation
date: 2024-06-30
excerpt: My very first project! Creating a makeshift SOC featuring SIEM, SOAR and case management.
cover:
alt: soc automation
image: /src/assets/project1.svg
tags:
- Projects
authors:
name: asd
title: asd
picture: https://avatars.githubusercontent.com/u/64679603
url: https://www.google.com/
---11:49:04 [WARN] [starlight-blog-plugin] It looks like you already have a MarkdownContent component override in your Starlight configuration.
11:49:04 [WARN] [starlight-blog-plugin] To use starlight-blog, either remove your override or update it to render the content from starlight-blog/overrides/MarkdownContent.astro.
After setting a custom ThemeSelect i get presented with the following in my log:
02:40:47 [WARN] [starlight-blog-plugin] It looks like you already have a `ThemeSelect` component override in your Starlight configuration.
02:40:47 [WARN] [starlight-blog-plugin] To use `starlight-blog`, remove the override for the `ThemeSelect` component.
I would love a toggle in the config to disable these warnings
This does not cause any real issue, more of just a console annoyance. for advanced use cases it would be nice to be able to disable the console warning when its intended that you are remapping the components for your setup.
No response
I am currently using the lastUpdated global config so under every page there is a lastUpdated date
it would be nice if they both had the same value
when turning on LastUpdated global config it should show the date up not down
Every time
No response
No response
error Cannot read properties of undefined (reading 'endsWith')
File:
node_modules/.pnpm/starlight-blog@0.2.1_@astrojs[email protected][email protected]/node_modules/starlight-blog/Tags.astro
Stacktrace:
TypeError: Cannot read properties of undefined (reading 'endsWith')
"@astrojs/starlight": "^0.9.1",
"astro": "^3.0.6",
"starlight-blog": "^0.2.1"
pnpm run build
Build Successful
Every time
macos;
No response
Yes, it's related to navigation issues within the site.
I would like a feature where a persistent navigation link or button is available that connects the blog section directly back to the documentation/wiki part of the site. This could be a simple "Back to Documentation" button or a more integrated navigational element in the site's header or sidebar.
No response
No response
If I have my base setting in Astro's astro.config.mjs defineConfig({}) of base: 'mysite',, then starlight-blog should generate links that use that config. But all links in starlight-blog are / instead.
For example base: 'mysite' should make the "blog" link in the navbar be localhost:port/mysite/blog but instead it's localhost:port/blog. Same for any links within the blog pages (if you know the url to access them and type them by hand).
I should mention my site is on Github Pages, to be colocated near my github project and since I don't want to shell out for a domain name. Github page urls are always my-account.github.io/my-repo/ so I always need to use the base for astro sites on it. I was hoping to use the blog module just for site update news.
Thanks for the nice module, hopefully I get to use it soon!
P.S. I would love the i18n #9 issue to get some love too but that's not nearly as high priority.
set base setting in defineConfig(), load your site, click on any links generated by starlight-blog to get a bad link.
It should take base into account.
Every time
No response
Adam M and Fryuni in Discord #starlight helped me out to make sure this wasn't just my noobness. They looked into it a bit and mentioned you may need to look at these files, but I don't know the project myself:
They also mentioned withastro/astro#10303 which is a similar problem elsewhere but documents the solution, using import.meta.env.BASE_URL to get the prefix that should be added.
I have starlight docs page that lives at /docs on my website. I'd love to also have a /blog route that uses this package but I wasn't able to get the two to co-exist.
Do you know if it's possible or how difficult this would be to support?
No response
No response
It would be nice to allow to add social images and an hero images. I say plural because I would expect to handle/provide images for dark and light themes.
Optional fields in the frontmatter should be enough
No response
I wanted to move the Biome blog to this integration, but we would lost the social images
It would be nice to be able to customize the url's!
The ability to change the path via the configuration
None
No response
Follow the steps in readme, after npm run dev, I got
> [email protected] dev
> astro dev
Re-optimizing dependencies because vite config has changed
16:49:06 [WARN] The injected route "/blog/tags/[tag]" by starlight-blog specifies the entry point with the "entryPoint" property. This property is deprecated, please use "entrypoint" instead.
16:49:06 [WARN] The injected route "/blog/[...page]" by starlight-blog specifies the entry point with the "entryPoint" property. This property is deprecated, please use "entrypoint" instead.
16:49:07 [vite] Re-optimizing dependencies because vite config has changed
astro v4.2.0 ready in 390 ms
┃ Local http://localhost:4321/
┃ Network use --host to expose
Looks like the blog is not enabled.
http://localhost:4321/ still shows the default starlight index.
follow the installation procedure in readme.md
should be able to see the blog
Every time
No response
No response
I really like your work @HiDeoo. While working with your code, I had some issues, especially since you are using some dependencies on your own code like your personal eslint configs etc. I found it a bit cumbersome to have to search for these on github to understand what is inside of them. It would be way more convenient, if they would be already on my disk, which would mean a monorepo. I think that approach would work quite well for a lot of your packages, for example also starlight-typedoc etc. Since you are already using pnpm workspaces, you already seem to know the gist. I can recommend turbo and changesets as additional tools to speed up things.
See above.
No response
No response
This bug appear when i start the local website
npm run devI just want to add blog because we need to post update of a game in it
Every time
No response
error Cannot read properties of undefined (reading 'endsWith')
File:
E:\VRCFR Site Web\vrcfr-creators-ts\eval at instantiateModule (file:\E:\VRCFR%20Site%20Web\vrcfr-creators-ts\node_modules\vite\dist\node\chunks\dep-df561101.js:55971:28
Stacktrace:
TypeError: Cannot read properties of undefined (reading 'endsWith')
at eval (eval at instantiateModule (file:///E:/VRCFR%20Site%20Web/vrcfr-creators-ts/node_modules/vite/dist/node/chunks/dep-df561101.js:55971:28), :62:63)
at AstroComponentInstance.Page [as factory] (eval at instantiateModule (file:///E:/VRCFR%20Site%20Web/vrcfr-creators-ts/node_modules/vite/dist/node/chunks/dep-df561101.js:55971:28), :21:12)
at AstroComponentInstance.init (eval at instantiateModule (file:///E:/VRCFR%20Site%20Web/vrcfr-creators-ts/node_modules/vite/dist/node/chunks/dep-df561101.js:55971:28), :32:29)
at bufferHeadContent (file:///E:/VRCFR%20Site%20Web/vrcfr-creators-ts/node_modules/astro/dist/runtime/server/render/astro/render.js:106:37)
at async renderToReadableStream (file:///E:/VRCFR%20Site%20Web/vrcfr-creators-ts/node_modules/astro/dist/runtime/server/render/astro/render.js:46:5)
at async renderPage (file:///E:/VRCFR%20Site%20Web/vrcfr-creators-ts/node_modules/astro/dist/runtime/server/render/page.js:29:12)
at async renderPage (file:///E:/VRCFR%20Site%20Web/vrcfr-creators-ts/node_modules/astro/dist/core/render/core.js:45:20)
at async #tryRenderRoute (file:///E:/VRCFR%20Site%20Web/vrcfr-creators-ts/node_modules/astro/dist/core/pipeline.js:99:18)
at async DevPipeline.renderRoute (file:///E:/VRCFR%20Site%20Web/vrcfr-creators-ts/node_modules/astro/dist/core/pipeline.js:46:20)
at async handleRoute (file:///E:/VRCFR%20Site%20Web/vrcfr-creators-ts/node_modules/astro/dist/vite-plugin-astro-server/route.js:155:18)
Sort of!
The RSS feed shows full-text in my feed reader (The Old Reader), but the images do not display. Instead, the alt-text is displayed.
I would love it if the full text of my RSS feeds displayed any included images.
I have not tested other feed readers besides The Old Reader so I don't know how common this issue is among feed readers/client.
No response
I wanna be able add an RSS feed to my blogs.
For there is be a way to generate the RSS Feed for the blog.
I'm very new to website creation, and Astro in general. I only understand RSS from a user perspective, and don't understand how it works. It seems to be a file hosted in a server, that updates every time a new blog post is posted. Hence, why, I decided to ask here if that could become a feature.
No response
Hey @HiDeoo, huge fan of what you've made. It would be great if we could mark posts that aren't yet ready to be published.
One of these new frontmatter propeties:
draft: true
isDraft: true
published: false (default: true)
isPublished: false (default: true)
Then when you're ready to publish, simply remove that line.
Alternatively, a _drafts directory. Then when you're ready to publish, simply drag+drop into the main folder.
No response
The dev toolbar complains about the images not being optimized
Define an author with a remote URL:
ema: {
"name": "Emanuele Stoppa",
"picture": "https://avatars.githubusercontent.com/u/602478?v=4",
"url": "https://twitter.com/ematipico"
}I expect no warnings from the dev toolbar
Every time
No response
No response
The plugin doesn't seem to be taking into an account srcDir
// https://astro.build/config
export default defineConfig({
srcDir: ".",
}astro build[vite]: Rollup failed to resolve import "/src/content/config.ts" from "virtual:starlight/collection-config".It builds instead of failing
Every time
No response
A temporary fix is just to have src/content/config.ts copy as well
running pnpm run build gives
20:34:49 [ERROR] [vite] x Build failed in 3.74s
[vite:build-import-analysis] [plugin vite:build-import-analysis] pages/_prefix_/rss.xml.astro.mjs (1:1): Parse error @:1:1
1 | import { o as objectType, a as stringType, u as unionType, n as numberType, d as dateType, b as arrayType, r as recordType, f as functionType, p as promiseType, c as anyType, e as preprocessType, g as booleanType } from '../../chunks/user-config_CU5WHklU.mjs';
| ^
2 | import { y as yellow } from '../../chunks/astro/server_gqeVL1Yw.mjs';
3 | import { c as config, g as getBlogEntries, a as context, b as getPathWithBase } from '../../chunks/content_D1pq9u3f.mjs';
Stack trace:
at parse$f (file:///Users/visual/Developer/ProjectSources/ChefKiss/ChefKissInc.github.io/node_modules/.pnpm/[email protected]_@[email protected]/node_modules/vite/dist/node/chunks/dep-D8YhmIY-.js:20510:585)
at file:///Users/visual/Developer/ProjectSources/ChefKiss/ChefKissInc.github.io/node_modules/.pnpm/[email protected]/node_modules/rollup/dist/es/shared/node-entry.js:19808:40
ELIFECYCLE Command failed with exit code 1.
pnpm up --latestpnpm run buildsite builds successfully
Every time
Many blog posts have a short timespan given in minutes as a estimated reading time for the whole blog post. This feature would perfectly fit for this project to I think.
Add another frontmatter field which is called something like readingTime and put the {value}min next to the creation date or something.
No response
I'm willing to create a PR for this.
The RSS feed is empty: https://starlight-blog-docs.vercel.app/blog/rss.xml
https://starlight-blog-docs.vercel.app/blog/rss.xml
The feeds should be populated with the content of the blog posts of https://starlight-blog-docs.vercel.app/blog/
Often
No response
No response
Porting from docusaurus to starlight(-blog) There is no embed image support. For eg- https://socialsharepreview.com/?url=https://wiki.x266.mov/blog/svt-av1-deep-dive and https://socialsharepreview.com/?url=https://codec-wiki.pages.dev/blog/svt-av1-deep-dive/
In frontmatter using image:
---
title: "Encoding Animation with SVT-AV1: A Deep Dive"
description: "With the recent release of SVT-AV1 1.8.0, how does it stack up for encoding animation?"
slug: svt-av1-deep-dive
authors:
- name: Trix
title: Encoder
url: https://github.com/trixoniisama/
image_url: https://avatars.githubusercontent.com/u/93526043
tags: [video, compression, benchmarks]
image: /img/svt-1.8.0-testing-blog-image.webp
hide_table_of_contents: false
---
### Describe alternatives you've considered
A auto generated embed image(if not specified in frontmatter) is also desirable but not necessary
### Additional Context
_No response_The native Next/Prev of Starlight makes sense for docs where you're moving to the next article in the documentation. But for docs you would expect Next to go to the next most recent blog post (i.e up the left nav, not down left nav).
This would also improve support for blog posts in a series (e.g. if I post a series of 3 posts, I can publish them one day apart, and then clicking Next would go to the next post in the series).
A isNextPrevChronological flag that defaults to true
No response
It looks like Starlight 0.9.1 introduced some changes in withastro/starlight#647 that change the internals that this integration relies on and are now breaking builds: tauri-apps/tauri-docs#1533
Update to Starlight 0.9.1 and attempt to build with the blog integration.
No go boom 💥
Every time
No response
No response
Right now, starlight-blog hardcodes all paths with no trailing slash. But the base starlight config allows setting trailing slash preference (in my case always). However the Blog engine will not respect that, which leads to unnecessary redirects when deployed.
Respect trailingSlash config.
No response
No response
Starlight Astro get his Page.astro in "Layout" and not "Layouts"
I expect to the website to build
Every time
No response
Here is the code i saw
declare module '@astrojs/starlight/layouts/Page.astro' {
export default function Page(props: Record<string, unknown>): unknown
}idk where else it is but when i change the path, i keep getting the error
Currently if I set the slug to my-post it will not get prefixed with blog/.
Which generates "incorrect" url
Either:
/blog (or custom path if #32 is considered)No response
No response
URLs in the sidebar & prev/next buttons don't respect trailingSlash, leading to an extra redirect on some hosts.
For URLs to end with /
Every time
No response
No response
It's not a real problem, just it's not the best idea to modify the source code on the node_module to change the language.
I think about a way to get the language selected on the astro config and use it for the default text on the blog compoment.
Creating a compoment to select the language of the blog, but it's not very optimized to have 2 language system
Example of what i write:
const blogSidebar = isBlog
? [
{
href: '/blog',
isCurrent: isBlogRoot(Astro),
label: 'All posts',
type: 'link',
},
{
entries: recentEntries.map((blogEntry) => ({
href: `/${blogEntry.slug}`,
isCurrent: isBlogPostPage(Astro, blogEntry.slug),
label: blogEntry.data.title,
type: 'link',
})),
label: 'Recent posts',
type: 'group',
},
]
: []with translation:
const blogSidebar = isBlog
? [
{
href: '/blog',
isCurrent: isBlogRoot(Astro),
label: translation.labelRoot,
type: 'link',
},
{
entries: recentEntries.map((blogEntry) => ({
href: `/${blogEntry.slug}`,
isCurrent: isBlogPostPage(Astro, blogEntry.slug),
label: blogEntry.data.title,
type: 'link',
})),
label: translation.labelRecent,
type: 'group',
},
]
: []And you can have a file like en.json :
{
"labelRoot": "All post",
"labelRecent": "Recent post"
}In all posts page, plain text and no image is previewed for a blog post. In docusaurus this is not the case
Eg- https://wiki.x266.mov/blog https://codec-wiki.pages.dev/blog/
Consider markdown and images when previewing posts
No response
No response
...
Can be convenient for daily use
No response
No response
Nothing big, but I'll be creating author profile pages for each defined author within the doc site itself, and having a the author link point to that. But this feels like it'd be nice to have out of the box!
It would be great to have these pages be auto-generated and as an option for where an author link goes to.
That way you can have a 'profile' built into the doc site itself, and being able to provide more details within the author schema so you can add as many external links as you'd like.
Haven't done anything yet, as I've just started getting things up and running today to use this for an internal docsite.
Thank you for creating so many useful plugins and integrations for Starlight!
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.