Support file names in code blocks

[thibaultamartin]

What version of starlight are you using?

0.11.0

What is your idea?

When writing documentation, it's often useful to show a file snippet to give readers a good idea of what they need to achieve and where (e.g. when updating a configuration file).

Being very explicit about which file is modified is useful to reduce the user confusion. For this, adding the file path and/or name right on top of the snippet is useful.

Why is this feature necessary?

This feature is useful to help user understand what file they need to edit when reading the docs.

Do you have examples of this feature in other projects?

Docusaurus uses a title property for code blocks: https://docusaurus.io/docs/markdown-features/code-blocks#code-title

Participation

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

[HiDeoo]

There is an ongoing effort to migrate Starlight code blocks to Expressive Code which supports this feature.

```js title="my-test-file.js"
console.log('Hello World!')
```

or even with:

```js
// my-test-file.js
console.log('Hello World!')
```

You can check a live preview here.

[delucis]

100% — we have an open PR for this feature in #742 and an issue tracking this in #461, so will close this as a duplicate, but thanks for letting us know this is something you’d like, that’s always great feedback to hear!