Choice of filename vs. title for code blocks

[JoshuaKGoldberg]

Coming over from eslint/eslint-plugin-markdown#226 -> eslint/eslint-plugin-markdown#230: we're discussing adding in support for specifying the file name of a code block:

```json filename="package.json"
{}
```

Docusaurus is notable in that it uses title rather than filename. We're leaning towards using filename rather than title in the proposal. So to be thorough: is there any reasoning behind Docusaurus using title? And/or, would Docusaurus be interested in adding filename as an alias?

An example of why this may impact some users would be:

• Users might have lint rules configured for specific file extensions, such as with eslint-plugin-jsonc for *.json files
• They may need to configure both the filename= and title= meta for those blocks to work for ESLint and Docusaurus, respectively

[Josh-Cena]

It's called title because well it's literally the displayed title. It can be used for many purposes other than filename (for example, what about title="ESLint config"?). Granted I don't think it would be bad for us to add filename as an alias.

[slorber]

Curious, what should be the visual outcome of this?

[JoshuaKGoldberg]

I'd assume the visual would be the same as if filename wasn't specified. So, Docusaurus would care about title visually, ESLint would care about filename for linting, and the two would never interact.

[slorber]

I'd assume the visual would be the same as if filename wasn't specified. So, Docusaurus would care about title visually, ESLint would care about filename for linting, and the two would never interact.

What prevents you from doing exactly that already?

```js filename="test.js" title="Test Title"
const test = 42;
```

Docusaurus would simply ignore the filename here so if you need it you can already add it.

https://stackblitz.com/edit/github-2zklxk?file=docs%2Fintro.md

---

By the way, the code block meta string is a non-standard format afaik. Not even sure it's safe to assume all users will want to specify extra attributes this way, although it seems quite common already. We might as well use an encoded query string or whatever else:

```js filename=test.js&title=Test
const test = 42;
```

---

Some projects use ESLint overrides to run different lint rules on files based on their file name.

Is there a very concrete example of this anywhere? I'm not sure to understand why you'd want that.

[JoshuaKGoldberg]

What prevents you from doing exactly that already?

Nothing that I know of. eslint-plugin-markdown doesn't yet parse any of these non-standard-format meta tags like filename and title. My goal here is to confirm that if it were to start parsing filename, this wouldn't inconvenience / interfere with Docusaurus at all.

Is there a very concrete example of this anywhere?

Yes, eslint/eslint-plugin-markdown#226 has one. Summarizing:

• In https://github.com/JoshuaKGoldberg/create-typescript-app, ESLint overrides are set up so that *.json files except package.json files have jsonc/sort-keys run on them
• There's a .md file with a codeblock intended to be a package.json
• ESLint is still running jsonc/sort-keys on that code block, even though I the user don't want it to
• I need a way to tell ESLint that the code block is a package.json file

[slorber]

😄 I see thanks

I don't think we plan to use filename now. If you want to only write filename and have it aliases to title, it should be possible through a remark plugin, and if we do want to introduce a filename feature later on, you could also "rename" it to "docusaurusFilename" through remark in case it cause any trouble.

So I'd say it should be fine for ESLint to use filename="package.json" and shouldn't mess up with Docusaurus. If it does, there will be solutions to handle potential conflicts.