Support for zero frontmatter in content files and/or remarkPluginFrontmatter

[delucis]

What version of starlight are you using?

0.36.0

What is your idea?

Currently Starlight requires a minimal frontmatter block in every content file:

---
title: Some title
---

All other frontmatter fields are optional, but we require title so we can populate things like sidebar labels, <title> meta, pagination links, and of course the actual on-page title field.

This discussion is to consider whether it could be possible to loosen this in some ways to support Astro’s remarkPluginFrontmatter, allowing title to be populated programmatically that way, e.g. extracting it from an h1 node, perhaps even doing that by default if title is not set.

Why is this feature necessary?

We’ve recently seen some requests to support no frontmatter, to make it easier to use content files that have a double purpose being rendered on e.g. GitHub, where frontmatter would make the file look less nice.

Additionally, for more advanced use cases there may be instances where remarkPluginFrontmatter can allow some dynamic control over frontmatter and avoid needing to manually set things repeatedly in frontmatter. It also provides an additional hook for people to have programmatic control over Starlight’s data model, which runs earlier than route data middleware: remarkPluginFrontmatter allows programmatic control at the content input level vs middleware which gives control over the Starlight data layer before rendering.

Historical context

One big reason for avoiding this in initial designs was performance: title is used in a lot of places, including on pages other than the titled page. For example, in an autogenerated sidebar, all link labels are pulled from the title fields of all pages. Extracting frontmatter values is much faster than parsing Markdown for all pages and so Astro split these two tasks into two chunks of work done separately:

1. Parse and validate frontmatter for all entries to create a content collection.
2. Only parse and process Markdown when a content collection entry is actually rendered.

This allowed for snappy dev server startup and updates by deferring Markdown processing. Having to process all Markdown for all pages to render one page’s sidebar is slow and we avoided that.

However, if I’m not mistaken, this two-step performance optimization was removed in the Astro v5 content collection re-architecting and now Markdown is once again processed upfront and cached in the collection. If that’s the case (we should confirm), and if there’s no intention to bring back the two-step process, then we could reconsider the design decision in Starlight to require title as the benefit would no longer be present.

Ideally, I’d argue that if Astro is committed to running the Markdown pipeline early, then integrating remarkPluginFrontmatter into regular frontmatter should be done at the Astro level, so that data flows as:

1. Markdown file is parsed
2. Markdown content runs, including plugins
3. Plugin frontmatter and file frontmatter are merged
4. Frontmatter is validated by the collection schema

This means users no longer have to deal with both entry.data and (await render(entry)).remarkPluginFrontmatter) and resolve that in templates, but can just rely on entry.data and schema types for a nicer DX.

Do you have examples of this feature in other projects?

• VitePress supports zero frontmatter (see e.g. https://github.com/vuejs/vitepress/blob/main/docs/en/guide/frontmatter.md)
• Docusaurus also doesn’t require title

Participation

• I am willing to submit a pull request for this feature.

[frodrish]

Hi @delucis,

I have made the minimal changes to make starlight work without frontmatter on my personal fork.

You can look at it here. Let me know if can and I should raise a PR.

The change consist on 4 main changes:

1. Created an example without fontmatter, I aslo wanted to show how to run from docs not in src/content folder
2. to utils/navigation.ts where is the sidebar label or fontmater title is not available I use the last part of the slug name
3. to utils/head.ts to skip undefined entries
4. to utils/routing/index.ts logic to threat undefined as draft false

I have explored the creation of a remark fontmatter plugin to get title from headers, but had 2 issues:

1. to register the plugin with astro hook.
2. The plugin was working properly outside astro, but was not when used with astro.

I can share more details if you are interested

Thanks

[frodrish]

@delucis, were you able to look at the changes? Note that for some reason github is overwriting my changes automatically everyday, created a new branch, I hope this will help

[delucis]

Looks like it’s there now — I’ll take a look!

[delucis]

Thanks for sharing. I think the approach you ended up at while technically functional is probably not something we’d want to use as-is for Starlight. It would move us from having a reliable source of page titles (with errors when people forget) to having a “best effort” at having a page title, trying to piece it together from Markdown or even file paths.

This also means the proposed code ends up doing quite a lot of “massaging” of data in various places where in general we try to keep things as clean as we can so that we have clearly separate stages to our pipeline:

1. Load and validate input content
2. Generate a route data model from content and config
3. Render that data to HTML (with as little business logic at this stage as possible)

This keeps our code base maintainable but also ensures we have a nice story for users to step in at each of those stages. (For example, route data middleware runs between steps 2 and 3 and allows users to change page data predictably. Having title just be in a single place makes route data easier to use.)

I think my requirement for this feature would be that the presence of a title is verified at the content input stage. It can be an h1 in the Markdown OR frontmatter, but absence of both is an error with the same level of user feedback as we have today. That would simplify things significantly and avoid stuff like the conditional rendering in PageTitle, falling back to filename parsing, etc. For example, I can already see bugs in relying on getTitle() which uses sidebar.label even for <title> etc. That kind of thing is easier to avoid if we don’t have this extra layer of logic to contend with.

This will need a bit or re-architecting of things as discussed in my opening post here, so may take a little while though, so using your solution as a patch in your code base might be a good approach for you for now. (I use pnpm patch for this usually, but there are options for other package managers too.)

[frodrish]

I agree these changes are not optimal, but maybe there is a middle ground here, if you exclude the place where the title is getting generated from the file name and the examples I added. Most of the changes I am proposing are handling cases where frontmatter related attributes are undefined. These changes do not even impact the business logic while ensuring proper behavior when title and sidebar are undefined, so maybe these can be merge.

A good example is this change in utils/routing/index.ts which from my perspective is addressing a bug in the code where undefined is considered as draft:

Original: return import.meta.env.MODE !== 'production' || data.draft === false;
Proposed: return import.meta.env.MODE !== 'production' || data.draft != true;

My interest is to have that supported in starlight it self, I would ratter not patch it outside, our goal is to use starlight as an entry point to astro and move some of our documentation sites away from vitepress. Unfortunately, in current state it is not possible. So, I would prefer to see the code merge here instead.

The current proposed patch is not preventing these architecture goals:

1. Load and validate input content
2. Generate a route data model from content and config
3. Render that data to HTML (with as little business logic at this stage as possible)

It just allow proper handling of content when the steps above fail.

Regarding your comment on getTille, we can always split it in two modes, but still better than undefined or a stack trace. Or maybe we can display a default value instead "ADD FONTMATTER TITLE"

To wrap-up maybe we can proceed with the changes on these files while a strategic solution get developed:

1. utils/head.ts (Assuming we use "ADD FONTMATTER TITLE" as title or "" instead of undefined ):
2. utils/navigation.ts
3. utils/routing/index.ts

main...frodrish:starlight:discussions3461

What do you have in mind in term of rearchitecture and why the above 3 changes would not be suitable as an interim solution?

Note that all our markdown files do not have fontmatter and a lot of them do no event have H1. Also if you look at some of the example I have added, when pages have H1 and title is provided it does not look good, so it might make sense in the strategic solution to allow to have different attributes for page title and navigation title.

[delucis]

Original: return import.meta.env.MODE !== 'production' || data.draft === false;
Proposed: return import.meta.env.MODE !== 'production' || data.draft != true;

This seems separate from the main topic here, but happy to take a look if you can provide a reproduction of when this actually causes issues (in a new issue). data.draft is always a boolean, with a default value of false set by our schema, so there should not be scenarios where this code is incorrect.

all our markdown files do not have fontmatter and a lot of them do no event have H1

How do you decide what these files should have as a title in VitePress? It’s an accessibility issue to not have an <h1> on every page and an SEO issue to not have a <title>, plus it breaks important Starlight features (e.g. sidebars and pagination) so I don’t see us ever supporting a scenario where there’s no way to get some kind of title.

In my ideal future, we will give some level of user control here though:

• Starlight uses title frontmatter or h1 automatically, otherwise errors.
• Users can provide additional logic we run against their Markdown if they want to provide additional strategies.

So for your use case, that second option would be available if you wanted to e.g. synthesise something from a file name.