code block \w filename

[jimmywarting]

hi 👋

today i saw another documentation today elsewhere and found this:

I struck me that many quite often want to present a code example and giving it an example filename along with it.
We sometimes see things such as:

```js 
// functions/_middleware.js

const errorHanddler = ...
```

i just thought that it would be a good idea if there was a spec'ed way of giving it an example filename:

```js filename=functions/_middleware.js
const errorHanddler = ...
```

[aidantwoods]

Nothing stopping an implementation from adopting what you've suggested whilst remaining CommonMark compliant right now. At the moment the spec doesn't mandate any particular treatment of the info string (not even the currently popular usage to specify the language is part of the spec currently).

The first word of the info string is typically used to specify the language of the code sample, and rendered in the class attribute of the code tag. However, this spec does not mandate any particular treatment of the info string.

Probably to have this standardised, it would be a prerequisite to first standardise the already popular language specifier in the info string.

[jimmywarting]

Probably to have this standardised, it would be a prerequisite to first standardise the already popular language specifier in the info string.

hmm, b/c the info string is so limited to just a single line... then i can think of 3 possible formats

• urlencoded
• json
• or how whatwg parse mime types key/values pairs

urlencoded

standarlize the info string to be something like a urlencoded;charset=UTF-8 body, with that you would be able to encode key/value pair that could include spaces and weird symbols... and there is already plently of encoder/decoder for urlencoded bodies already out there in different languages

javascript: example: new URLSearchParams({filename: '_middleware.js', foo: 'bar & baz'}).toString()
produce: '''js filename=_middleware.js&foo=bar+%26+baz

the holy json

With json you would get support for other typed values like numbers where you wish to hint about eg the file size.

javascript: example: JSON.stringify({filename: 'index.html', size: 321, type: 'text/html'})
produce: '''html {"filename": "index.html", "size": 321, "type": "text/html"}

Maybe a bit verbose? either way... simple to encode/decode.

mimetype parsing metadata

This leave me to the last and final solution (suggestion)
mimetype parsing according to something like: https://www.npmjs.com/package/whatwg-mimetype
here all the key/values would be seperated by ; and every key is according to whatwg specifications case insensitive.

an example: '''html text/html; filename=some name.html; size=321

tings that could be nice to present if the markdown decoder could would be to find useful informations such as

• filename or just full path
• total file size
• last modified
• type
• if it's partial code
• start/end of line
• lines to highlight

github's permalink could be something of a inspiration:
https://github.com/commonmark/commonmark-spec/blob/19836055749b28a9fd57beb97c0efe707bd42f7e/Makefile#L8-L9

commonmark-spec/Makefile

Lines 8 to 9 in 1983605

	spec.md: spec.txt tools/template.commonmark
	lua tools/make_spec.lua commonmark < $< > $@

[Crissov]

https://talk.commonmark.org/t/code-blocks-extension-for-filenames-and-line-numbers/536