CODEWITHSUNDEEP
markdown
BCDeWitt
BCDeWitt

Reputation: 4773

Semantic Markdown file/directory path

A common practice in Markdown to handle file/directory paths that are not intended to be links is to use backticks, which mark content as "code". This practice even happens here on SO. My question is, is there a more semantically correct option? I don't think file paths are technically considered "code". Even my own words here seem suspect to me, which leads me to a second, highly related question. Why would a path ever match this "not intended to be links" criteria?

For more context, I came up with this question while trying to add setup instructions into a README.md file for a coding project. Here, I'm trying to refer to a folder, src/io. Introspecting a bit, my thought was: "Maybe it would be better to mark paths like this differently - maybe as a link, even if clicking it doesn't always work?". But, this doesn't cover cases like with SO questions/answers, where you only have a hypothetical path (maybe this is the criteria?).

Upvotes: 5

Views: 4703

Answers (1)

Waylan
Waylan

Reputation: 42497

Yes, code spans are the correct way to mark up filenames and paths.

A Markdown code span renders to an HTML code element. The HTML spec states (emphasis added):

The code element represents a fragment of computer code. This could be an XML element name, a file name, a computer program, or any other string that a computer would recognize.

That explicitly calls out file names as acceptable content of a code element. While directory paths are not mentioned specifically, the expression "any other string that a computer would recognize" would certainly include both.

But, this is Markdown, not HTML... then may I remind you that Markdown is a subset of HTML as explained in the original Syntax Rules. And, as explained there...

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself.

So, the correct way to mark up filenames and paths in HTML would be the same in Markdown. Of course, as Markdown supposes code spans (using backpacks) you don't need to use the raw HTML code elements. The backticks are an easier to read and write shortcut.

But, when would paths not be links?

Whenever they are not pointing to a reachable location. Here on SO we regularly see questions with paths to local files and directories. If I post a question about how to access a local file on my local system, you wouldn't expect to click a link and have access to the file. I would need to upload the file for that. However, to properly report by situation, I need to use the local path, which is not reachable online. Therefore, such paths should not be links. It doesn't matter if they are pseudo paths or real paths.

Upvotes: 6

Related Questions