Allow renaming labels of nested autogenerated folders in sidebar

[Swader]

What version of starlight are you using?

0.11.0

What is your idea?

Currently an autogenerated sidebar inherits the folder name. Obviously, this prevents casing and spaces in the name, which makes it look odd in the sidebar.

We should be able to define subgroup labels and settings per subfolder somehow - either with a _metadata.json file in the subfolder, or some more config options.

Why is this feature necessary?

Current inability to do this makes verbosity in the sidebar harder, and can break style / clarity.

Do you have examples of this feature in other projects?

Docusaurus

Participation

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

[HiDeoo]

This is indeed something that is still under discussion until a good solution is found.

One temporary workaround (which obviously does not scale well) could be moving the autogenerate config one level deeper, e.g.:

{
  label: 'Explanations',
  items: [
    { label: 'Overview', link: 'explanations/overview' },
    { label: 'Decentralized Storage', link: 'explanations/decentralized-storage' },
    { label: 'Usecases', autogenerate: { directory: 'explanations/usecases' } },
  ],
}

[raviqqe]

Is it possible to pass a general JS function to the configuration like the following?

{
  label: "Foo bar baz",
  autogenerate: {
    directory: "foo",
    subDirectoryLabel: (path) => capitalize(basename(path).replace("-", " ")),
  },
}

[HiDeoo]

Is it possible to pass a general JS function to the configuration like the following?

This is not a supported syntax at the moment.

To give a bit more context on why this is not supported, the way things work today is the following:

• A user passes down a configuration object to the Starlight integration
• The configuration is parsed/validated
• A virtual module (virtual:starlight/user-config) is created to re-export the user's configuration
• At this point, Starlight can import that virtual module to access the user's configuration

When creating the virtual module, we need to create a string representation of the user's configuration, i.e. serialize it. This means that we can't pass functions across this boundary.

[Fryuni]

Just to disagree with you a little bit for fun. It is possible to do that IF you are using output: 'static' or if that code path is never run outside of the build. Since Starlight doesn't support SSR (yet) and the code path that would be affected by this is not exposed to consumers of the library in a way that could be used on custom routes, then it is possible for Starlight to receive a function inline in the configuration.

[raviqqe]

Hmmm, I see. In that case, I propose simple mapping from --separated (I believe this is the most common) basenames in paths to certain cases users choose.

{
  label: "Foo bar baz",
  autogenerate: {
    directory: "foo",
    labelCase: "sentence",
  },
}

The type of labelCase would be like "sentence" | "title" | "lower" | "upper".

• URL structure best practices for Google

[Swader]

I like this label mechanic, simple and covers most use cases - for me, as long as I can have a one-word directory shown as a correctly cased phrase, I'm good.

[Swader]

How do we move ahead with this? Who needs to approve it?

[delucis]

I think we probably need to think if we can come up with a more general solution to labelling here. While changing sentence case is a good start, we also have the issue of sites with multiple languages who want to translate the directory name.

One option could be to add a labels map to the autogenerate config something like this:

[
  {
    label: 'Examples',
    autogenerate: {
      directory: 'examples',
      directoryLabels: {
        'examples/php': 'PHP',
        'examples/js': 'JavaScript', 
      },
    },
  },
  {
    label: 'Guides',
    autogenerate: {
      directory: 'guides',
      directoryLabels: {
        // Labels for different languages
        'guides/styling': {
          en: 'Styling',
          fr: 'Mise en forme',
        },
      },
    },
  },
]

[delucis]

Not sure if we’d support that automatically because of how we validate those JSON files to match a specific schema (and supporting any directory structure would mean accepting any keys in those files), but if we went this route, you could import some other JSON files into your config if you preferred that:

import { defineConfig } from 'astro/config';

import en from './src/directoryLabels/en.json';
import fr from './src/directoryLabels/fr.json';

const languages = { en, fr };
/** @type {Record<string, Record<string, string>>} */
const directoryLabels = {};
for (const [language, labels] of Object.entries(languages)) {
  for (const [key, value] of Object.entries(labels)) {
    if (!directoryLabels[key]) {
      directoryLabels[key] = {}
    }
    directoryLabels[key][language] = value;
  }
}

export default defineConfig({
  integrations: [
    starlight({
      sidebar: [
        {
          label: 'Guides',
          autogenerate: { directory: 'guides', directoryLabels },
        },
      ],
    });
  ],
});

Same general idea applies for other cases if you’re finding the config hard to manage.

[dymo]

Cool idea.

I would need to make something similar for translating the root items ('Guides' and 'Examples').

Will I break something if I put those json files in the docs or i18n directory?

e.g.
./src/content/docs/fr/directoryLabels.json
or
./src/content/i18n/directoryLabels_fr.json

[HiDeoo]

Will I break something if I put those json files in the docs or i18n directory?

You cannot mix content (.md, .mdx, etc.) and data (.json, .yaml) entries in the same directory so putting the file in src/content/docs/fr/directoryLabels.json will raise an error but you can exclude entries from being built by prefixing the filename with an underscore (_).

[LuHugo]

I saw that docusaurus solved this problem by adding a _category_.json or _category_.yml file under the folder to describe the folder.

{
  "position": 2.5,
  "label": "HTML Tutorial",
  "collapsible": true,
  "collapsed": false,
  "className": "red",
  "link": {
    "type": "generated-index",
    "title": "Tutorial overview"
  },
  "customProps": {
    "description": "This description can be used in the swizzled DocCard"
  }
}

https://docusaurus.io/docs/sidebar/autogenerated#category-item-metadata

[mavam]

Coming from Docusaurus and evaluating Starlight, landed here. I'm a bit baffled. Is there really no integrated solution to creating a controllable document structure?!

[swenzel-arc]

IMHO a yaml, json or md file with a special name is the way to go. Being able to change the label is only one use-case. In my case I'd like to change the position and the collapsed state as well. Therefore, a mere "labelling mechanic" wouldn't help me.

Docusaurus has already been mentioned. I'd like to add that HUGO also takes a similar approach with special files called _index.md: https://gohugo.io/templates/lists/#add-content-and-front-matter-to-list-pages

[delucis]

Thanks for sharing!

Given needing that level of control, may I ask why you prefer not specifying the sidebar explicitly in the Starlight config? What are the benefits to controlling this in multiple metadata files vs in a single config array?

[swenzel-arc]

Given needing that level of control, may I ask why you prefer not specifying the sidebar explicitly in the Starlight config?

Sure! So the thing is, we have a central documentation repository that is importing subdirectories from other projects. These subdirectories are listed as autogenerated groups so the external repos can determine the structure on their own.
I wasn't the one who set it up but I guess importing a well defined JS file from the external repos and then stitching together the sidebar config would be possible but for me that feels like a workaround. It just seems natural to allow (sidebar-related) metadata for folders if it is already allowed for docs.
So in a nutshell: We'd like the directories to be decoupled from the main config.

What are the benefits to controlling this in multiple metadata files vs in a single config array?

Well... you could ask the same question about config array vs. autogenerated groups in general.

[delucis]

Thank you — very helpful for us to understand the use case.

[oliwarner]

This is my preferred way of doing this too. Don't centralise it. Leave it with the content; a metadata file in the subdirectory that explains what's going on. .group.md would be in-keeping with the existing naming (these subdirectories are "groups"), and just using frontmatter would keep it aligned with other configuration.

11ty does similar things.

[LuHugo]

Is there any progress on this?

[FredericLatour]

Even though I can understand some hesitation due to how collections work, using a configuration file starting with an "_" (a la docusaurus) is the way to go for consistency and convenience.
That would be really weird to have 2 different approaches for naming and ordering folders and documents (in an autogenerated context).

[rdela]

Preceding context for prev comment from Starlight Discord:

F: Any way to have a specific order for a subfolder (autogenerated)? […]

C: […] Generally I recommend specifying the the upper level manually […], and then including the subdirectory in there (auto-generated or not as you prefer) […]

F: Docusaurus makes it possible to add a _category_.yaml file in a folder. This makes it possible to use the same configuration option that you can use in the frontmatter of any md/mdx file. Using this approach, you can specify both the name and the order of the folder without sacrificing the autogenerated approach.

[ntrp]

I also believe the docusaurus approach is more than fine and was surprised it's not already the case, has the be any further discussion regarding this feature? Would you accept a PR if somebody would implement it?

I am willing to implement it if the team is fine with the solution.

[lorenzolewis]

I was looking into this a bit today and re-discovered that Astro's Content Collections (which are the backbone of Starlight) ignore files starting with an _:

You can also exclude entries from being built by prefixing the filename with an underscore (_).

https://docs.astro.build/en/guides/routing/#excluding-pages

My initial thought was to use something like _index.[md|mdx] to store the "category"'s metadata but it seems that naming convention isn't do-able because of this.

[dacevedo12]

another option

.sidebar-content .group-label {
  text-transform: capitalize;
}

[dsalaza4]

You must add this piece of code to src/styles/custom.css as explained here: https://starlight.astro.build/guides/css-and-tailwind/#custom-css-styles

[mavam]

This unfortunately breaks when capitalization is not desired, e.g., in case of acronyms. There's no way around a manual mechanism to supply sidebar labels.

[olton]

Hi guys! Maybe it will be useful to someone, for me I solved this problem in the following way:

I created a function that recursively runs through the directories and generates the corresponding nodes for the sidebar:

Caution

each folder must contain file __section.md with one line: # Folder Title

import fs from 'fs'
import path from 'path'

const sidebar = []
const root_docs = ["src", "content", "docs"].join(path.sep) + path.sep;

function traverseDirectory(dir, parent) {
    try {
        // console.log(dir)
        parent.label = fs.existsSync(dir + path.sep + "__section.md")
            ? fs.readFileSync(dir + path.sep + "__section.md", 'utf8').split("\n")[0].replace('#', '').trim() :
            dir.replace(root_docs, '');
        
        const entries = fs.readdirSync(dir, {withFileTypes: true});
        
        entries.forEach(entry => {
            const fullPath = path.join(dir, entry.name);
            if (entry.isDirectory()) {
                const new_section = {
                    label: entry.name,
                    collapsed: true,
                    items: []
                }
                parent.items.push(new_section)
                traverseDirectory(fullPath, new_section);
            } else {
                if (entry.name.includes("__section")) {
                    // skip __section.md
                    return
                }
                const slug = `${fullPath.replace(root_docs, '').replace(/\\/g, '/')}`.split('.').slice(0, -1).join('.')
                parent.items.push(slug)
            }
        });
    } catch (err) {
        console.error(`Error reading directory ${dir}:`, err);
    }
}

export default function (root, collapsed = true){
    sidebar.length = 0;
    const _parent = {
        label: root,
        collapsed,
        items: []
    }
    sidebar.push(_parent)
    traverseDirectory(root, _parent);    
    return sidebar;
}

And then I add this to the sidebar:

import getSidebar from "./tools/generate-sidebar.js"


export default defineConfig({
    base,
    trailingSlash: "never",
    integrations: [
	starlight({
    	    sidebar: [
		{label: "Introduction", slug: "introduction"},
   	        ...getSidebar("./src/content/docs/getting-started", true),
		...getSidebar("./src/content/docs/fundamentals", true),
		...getSidebar("./src/content/docs/tutorials", true),
 	        ...getSidebar("./src/content/docs/how-to", true),
		...getSidebar("./src/content/docs/data-model-editor", true),
		...getSidebar("./src/content/docs/release-notes/", true),
		...getSidebar("./src/content/docs/api-reference/", true),
 	    ],
	}),
    ],
});

[mavam]

Could someone explain to me how Clickhouse gets this working?

Check out their config:

async function autogenSections() {
	const sections = (
		await readdir("./src/content/docs/", {
			withFileTypes: true,
		})
	)
		.filter((x) => x.isDirectory())
		.map((x) => x.name);
	return sections.map((x) => {
		return {
			label: x,
			autogenerate: {
				directory: x,
				collapsed: true,
			},
		};
	});
}

const sidebar = await autogenSections();

[HiDeoo]

Sharing a plugin based approach I just released that supports defining custom labels for directories and a few other features to tweak autogenerated sidebar groups: starlight-auto-sidebar

[mavam]

This is great!

Unfortunately it interferes with Starlight Utils. For example, adding label: My Custom Title doesn't have an effect when Starlight Utils is loaded. If I remove Starlight Utils, your plugin works.

I probably will have to re-implement a light-weight version of Starlight Utils that provides navbar links at the top to have multiple pages with subsets of the sidebar.

[lorenzolewis]

Hi @mavam ! I'm the author of Starlight Utils. This shouldn't be the case I don't think 🤔 The plugin should only do anything with the sidebar if you've set something in the multiSidebar property of the plugin. Feel free to open an issue with a reproduction and I can take a look to see what's going on.

[lrstanley]

Not a huge fan of having to have a bunch of extra files spammed across our repo. any chance there is a way to achieve the same through something like... schema extensions, and specifically on index files? i.e. if an index.<md|mdx|etc> file has a specific frontmatter schema config, the parent directory uses the plugins schema fields to determine what the settings should be? this way is doesn't interfere with the structure of the repo, and users don't have to necessarily learn how the _meta file works?

[HiDeoo]

Not a huge fan of having to have a bunch of extra files spammed across our repo. any chance there is a way to achieve the same through something like... schema extensions, and specifically on index files? i.e. if an index.<md|mdx|etc> file has a specific frontmatter schema config, the parent directory uses the plugins schema fields to determine what the settings should be? this way is doesn't interfere with the structure of the repo, and users don't have to necessarily learn how the _meta file works?

I tried various approaches before deciding on the one I'm currently using, including one similar to the one you're describing, although if I'm not mistaken, this would end up being quite similar as a user would need to create index.md files where needed to tweak the parent directory. It also has the downside of creating pages, e.g. if my directory does not have an index.md file with some content, creating one to just tweak the parent directory would create a page with no content that the user might not want.