1

It's relevant and useful to include the name of the file that a code block should go in. For example, an update to a Next configuration would go in the next.config.js file, an NPM script would go in the package.json file and so on..

Specifying the filename is already done in answers, and visually it would make sense to more closely couple this information with the code block.

For example, in my most recent answer I did this:

Enter image description here

A more digestible and compact way to do this would be to stick that information in the top-right corner of the code block:

Enter image description here

A proposed Markdown syntax for this could be

````js, next.config.js

A Markdown syntax update would probably be the biggest blocker on this feature request.

13
  • 14
    I disagree somewhat on your proposed new layout. For me, sticking the name off to the right, away from the normal flow of text, makes it much easier to miss. I would prefer just having a bold heading immediately above the code block, which is already easily achievable via Markdown.
    – Cody Gray Mod
    Commented Apr 14, 2022 at 22:36
  • 4
    Even if the new layout is better, which I'm not sure I agree with, can you argue that it provides enough of a benefit to justify the developer time it would take to implement it? Commented Apr 14, 2022 at 22:37
  • I think part of why I would find this useful is that a lot of answers omit this information and just assume the reader knows what file they're talking about. This flow would not require the people who already know this information to read it, but if someone is wondering where this snippet should be going, they can look off to the right. Commented Apr 14, 2022 at 22:39
  • 4
    This seems like something that's easily solved by using a level 4, 5, or 6 header for the file name, just prior to the code block. Please use actual headers for section headers, rather than bold text. Please don't use code formatting for non-code/data/error text (i.e. file names on their own really aren't appropriately formatted as code). BTW: As you are almost certainly aware, I edited your answer to demonstrate what I was meaning. I'm not going to object to you rolling it back if you don't like it.
    – Makyen Mod
    Commented Apr 14, 2022 at 23:39
  • 1
    @Makyen Please don't use a level 4 header (much less 5-6) unless you have used level 2 and 3 headers above that. Headers need to be sequentially increasing on the page for people who use assistive technology.
    – Laurel
    Commented Apr 15, 2022 at 0:51
  • 1
    @Laurel Please provide an example of an assistive technology which doesn't handle headers which are at least logically ordered when a level or two of headers are not provided. I'm not saying you're wrong, merely that it doesn't match with my experience, nor what I'd expect from even a bare-bones implementation.
    – Makyen Mod
    Commented Apr 15, 2022 at 0:56
  • Sugg got a mini-(+1) from me, even if I actually more agree with the Comments from #Cody + #Makyen (+ #Laurel's Answer), and I'm not "completely convinced/seduced" by your Explanation, but I see other "Usecases" (for other Tags) where that Syntax/Layout could maybe be handy indeed (sometimes!)... (But not too much Promotion about it if it gets implemented, reserved to "Advanced" Users..., maybe "Unlocked" after they used at least x10 the -lang Syntax in Code Blocks... (+ In at least 5x (Accepted) Answers...!) :razz:
    – chivracq
    Commented Apr 15, 2022 at 1:01
  • @Laurel I should include the criteria for the example I'm requesting that the assistive technology is worse based on the skipped levels of headers. Given that any post can create any level of header, headers on SE question pages don't, necessarily, follow a logical order within the page. In other words, I'm asking for an example of something that's notably worse based on using skipped levels of headers within the same post, excluding interactions with other posts (as those are not reasonably controllable by a single poster).
    – Makyen Mod
    Commented Apr 15, 2022 at 1:06
  • Yep, easy Sol: Assistive Tech should get "smarter"...!
    – chivracq
    Commented Apr 15, 2022 at 1:11
  • 1
    @Makyen Headings are used by screen reader users. Here is a good explanation of why the headers should be in the proper order: "I usually try to find a heading and then go from there. Usually, I do this by pressing the #1 or #2 on the keyboard, since the hope is that a competent web developer coded the site and that headings are where and at the level they should be."— Screen reader survey response.
    – Laurel
    Commented Apr 15, 2022 at 1:20
  • @Laurel, I would have "quite a lot to say" about Accessibility and Screen Readers, but such a "Discussion" will actually "pollute" this current Thread, maybe want to open a separate Thread...? :idea: // I was "once" (10-12 years ago) responsible for Accessibility and Screen Readers Access for 2 Official Websites for 2 (NL) Ministries (MinFin and MinBuza), and I'm nearly surprised to see that your Article/Link from 2016 has "nothing new" compared to when I was active in that Field, but 6 years later, common on...!)
    – chivracq
    Commented Apr 15, 2022 at 1:53
  • 2
    "I think part of why I would find this useful is that a lot of answers omit this information and just assume the reader knows what file they're talking about." then how does this suggestion help? Surely if somebody doesn't include the information, then it doesn't matter where it is not displayed. If the OP does include it then it doesn't really hinder anybody where the information is displayed.
    – VLAZ
    Commented Apr 15, 2022 at 4:40
  • 2
    I think filename is too specific. Code blocks could use an optional title, what you put in the title is up to you. This would play into the wiki/knowledge base aspect of the site, in a typical wiki it is also possible to label images and particular marked sections to aid in providing context.
    – Gimby
    Commented Apr 15, 2022 at 9:27

2 Answers 2

9

It's relevant and useful to include the name of the file that a code block should go in

Not always. Many questions give a short block of text as an example of where they're having the problem, and answers respond with an amended version of the code block. It doesn't matter what the name of the file is (it really could be anything with an appropriate extension). The code might not even be for a file! Most regexes, for example, can be used in almost any language, but where I find myself using them most often is in the search box of my IDE. Furthermore, not everything that finds itself in a code block is even code (e.g. error messages).

Needless to say, you don't need to provide a file name (or even a context) for every block of code. So we're back to the start: People will still assume they don't need to include the file name when it would be helpful to do so. Or maybe people will include a file name in contexts where they don't need to, making the post noisier.

Lastly, I prefer regular markdown formatting (if not plain text) over your suggestion, both aesthetically and formatting-wise — your suggested format is much too tricky for the vast majority of people to use.

5
  • "your suggested format is much too tricky for the vast majority of people to use." => Yep indeed, completely agree, => seen my Comment above to the Qt itself... (I tried to address that Concern...)
    – chivracq
    Commented Apr 15, 2022 at 1:08
  • @chivracq Your suggestion seems to make it even more complicated. A new user will copy the markdown from another answer and... it just won't work? The calculation you proposed would be hard to implement. And most users shouldn't have to specify a language for their code. Having a tag like c# should provide it automatically, instead of having to remember whatever the language code is for it. (I'm not a fan of how hard it is to do language highlighting...)
    – Laurel
    Commented Apr 15, 2022 at 1:35
  • "Your suggestion seems to make it even more complicated." => Yep indeed, was "the Purpose", => (reserved) for "Advanced Users" I mentioned, trying to address your "your suggested format is much too tricky for the vast majority of people to use.". // Automatically having that Option for "specific" Tags could be an Option indeed, but pfff, there will always be an "Advanced" User in any Tag on the Site that will want it... I WANT IT if it gets implemented, for my "small" Tag (imacros), I'm the only Active Advanced User monitoring/answering that Tag ([2020-2022])...
    – chivracq
    Commented Apr 15, 2022 at 2:32
  • "A new user will copy the markdown from another answer and..." => Oh...!?, OK, I don't "know" that, this never happens in "my" Tag, "New Users" (= 95% of the Askers) have 1-Rep, and they only ask Qt's, ah-ah...!, I'm the only one answering...! I'm already "Happy" if they manage to find ____ (4 Spaces) to format their Script a bit correctly...!
    – chivracq
    Commented Apr 15, 2022 at 2:41
  • I never saw this as a requirement or a thing that would show up on every code block. The code block language-specific syntax highlighting is something you can optionally add to code blocks when it's useful. I imagine a filename would work similarly. Commented Apr 15, 2022 at 17:29
8

I fully agree with the proposal and I don't understand all of the downvotes.

This is already doable e.g. via python markdown extensions, like this:


    ``` py title="bubble_sort.py"
    def bubble_sort(items):
        for i in range(len(items)):
            for j in range(len(items) - 1 - i):
                if items[j] > items[j + 1]:
                    items[j], items[j + 1] = items[j + 1], items[j]
    ```

See here:

1
  • 1
    Many of the naysayers are just arguing that there will be blocks that don't need/have a file name. But the argument doesn't make any sense, the old block syntax would still work as before, since the title should be optional.
    – renke
    Commented May 21 at 14:00

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .