docs: Format paths as code

[salim-b]

No description provided.

[jmooring]

I am aware of this stylistic inconsistency in many of the pages on the site. We need to get consistent, but I'm not sure which way to go. I'm leaning towards not formatting file names and paths as code because...

1. The formatting can be a distraction
2. In some cases it doesn't look great
3. The MS Style Guide, which we sometimes use for guidance, does not explicitly require formatting (plain text is fine). See https://learn.microsoft.com/en-us/style-guide/text-formatting/formatting-common-text-elements.

I'll leave this open for now.

[salim-b]

I totally agree about the goal of consistency!

I just prefer the opposite, i.e. formatting filesystem paths as code because...

1. It's the opposite for me. It's rather common to format FS paths as code in software documentation, so I expect the paths to be visually distinguishable from regular prose when looking for specific information. Having them not formatted regularly leads to me overlooking the information I'm after.

2. I guess I disagree. Also, I think there are various cases where it is rather confusing to not format FS paths as code like relative hidden paths (e.g .bashrc), paths that start with underscores (e.g. _index.md) or single filenames in general.

3. Ok. I don't know this styleguide. But it doesn't seem to make much use of formatting as code in general while the Hugo docs generally use this a lot ... the only element suggested to be formatted as code in that MS styleguide table are macros.

4. IMHO, formatting FS paths as code makes it much easier to spot fine variations like index.md vs. _index.md etc.

How would you like to proceed about deciding which way to go? Should simply @bep decide? Or should we make a poll in the forum? Something else?

[jmooring]

Let's make a data-driven decision...

Style Guide	Use monospace font for file names/paths?
Microsoft	No
Apple	No
Google	Yes
Chicago Manual of Style	Ambiguous
AP Style Guide	Ambiguous
Digital Ocean	Yes
GitLab	Yes
GitHub	Yes

As this is a Go project, I'm inclined to follow Google's style guide, which falls back to the Microsoft style guide when guidance is not explicit.

Regarding appearance, I guess we can adjust the CSS at some point if anyone cares enough. I've never been a fan of the lower baseline and smallish font.

[salim-b]

Nice overview! I think software-(company-)specific guidelines are more relevant for Hugo than academic or journalistic ones like "Chicago Manual of Style" or "AP Style Guide". At first glance, I like Google's style guide, especially that they have a rather elaborate section about Code in text with many examples. They also provide examples for the most important items to put in ordinary (non-code) font.

Regarding appearance, I guess we can adjust the CSS at some point if anyone cares enough. I've never been a fan of the lower baseline and smallish font.

Agreed. The current styling of the Hugo docs is not so bad, though (baseline seems fine; font size could be increased a little and the grey background made a bit darker to increase contrast).

[jmooring]

@salim-b

Maybe we make an exception for headings.

[salim-b]

Maybe we make an exception for headings.

I'd like to include headers. Why would you except them?