Allowed characters in file paths and slug front matter

[bsmth]

We have an open pull request that renames a few files: mdn/content#20470

Background:

• 6 pages in the repo have parens in the title, e.g, /path/to/function_(CSS)
• markdownlint can't fix changes inside the files because it can't handle this path format (yet)
• This PR wants to change them to something like /path/to/CSS_function

What to decide:
Thanks to @teoli2003 for suggesting the following to discuss:

• What characters to exclude and why (forbidden by standard, making automation complicated because they have a special meaning in shells, risk of spoofing, …)
• What conventions do other large websites have.
• What has to be updated (# pages to rename, meta-docs to update, scripts to guarantee the problem doesn't come back, …).

I would also quote @Josh-Cena who had a proposal for the specific PR:

keeping parentheses in slugs (but) remove them from file paths

This would get rid of the need to add/change redirects, and allow linting tooling to parse the paths properly.

List of files (if slug is single-line value):

grep -rE "slug:.+?\(" files
files/en-us/web/css/_colon_-moz-locale-dir(ltr)/index.md:slug: Web/CSS/:-moz-locale-dir(ltr)
files/en-us/web/css/_colon_-moz-locale-dir(rtl)/index.md:slug: Web/CSS/:-moz-locale-dir(rtl)
files/en-us/web/http/cross-origin_resource_policy_(corp)/index.md:slug: Web/HTTP/Cross-Origin_Resource_Policy_(CORP)
files/en-us/glossary/round_trip_time_(rtt)/index.md:slug: Glossary/Round_Trip_Time_(RTT)
files/en-us/glossary/xhr_(xmlhttprequest)/index.md:slug: Glossary/XHR_(XMLHttpRequest)
files/en-us/glossary/descriptor_(css)/index.md:slug: Glossary/Descriptor_(CSS)

[dipikabh]

If possible, I would suggest to keep the slug same as the file name (remove parenthesis from both), so that it is easier to remember the guideline and keep things consistent.

[Josh-Cena]

FWIW, we already have this inconsistency. :has becomes _colon_has for file path; function* becomes function_star_ for file path. Sanitizing parentheses is no worse than those.

[dipikabh]

I see a pattern in those - the special character in the slug is spelled out in the file name. That's easier to internalize. 🙂

[OnkarRuikar]

Having same filename and slug name is good for automation and backend maintenance.

[nschonni]

There are a few buckets here:

1. Files with functions Web/CSS/:-moz-locale-dir(ltr)
   • Other special characters like : have been substituted before. No idea about a good pattern for these
2. Files with spelled out acronyms Glossary/Round_Trip_Time_(RTT)
   • Could drop the acronym entirely, and just add a redirect for the acronym to the full file
3. Files with Disambiguation Glossary/Descriptor_(CSS)
   • There is just the single case of this one, and the file actually seems misnamed when I did the other PR

[OnkarRuikar]

What characters to exclude and why (forbidden by standard, making automation complicated because they have a special meaning in shells, risk of spoofing, …)

• For automation and tooling special characters in Bash script could cause problems due to various shell expansions. Same can be said for PowerShell on Windows.
• Special characters in RegEx ., +, *, ?, ^, $, (, ), [, ], {, }, |, \. Because tools used may not always escape them in parameters.
• Special characters in globs
• For security removing special characters covers most of the cases. We can limit to only underscore and hyphen.

What conventions do other large websites have.

The document https://github.com/bartvandebiezen/file-name-conventions has a lot of good points.
We should come up with our own naming convention like this, and document it in writing guidelines. It will not only solve this issue but will bring uniformity across the repo.

---

Using what the element is better than mimicking the syntax (colon_moz-locale-dir).
For cases like Web/CSS/:-moz-locale-dir(ltr) we could use:

• class-moz-locale-dir
• pseudo_class-moz-locale-dir

generator_function sounds better than function_star.

I like the idea of dropping acronym and using only the full form.

[Josh-Cena]

generator_function sounds better than function_star.

Are you suggesting changing the slug as well? That's not feasible—I suppose both in and out of JS. Partly because it makes {{jsxref("function*")}} unusable. Partly because that's not consistent with most other expressions/statements' slug, which prefers using the keyword itself where possible.

[OnkarRuikar]

For the convenience of using the symbols in ref URLs yari has to do hardcoded conversion. This makes it hard to get rid of these ref macros in favour of simple markdown style URLs [function*](en-US/docs/…/generator_function).

Using syntax as it is in URLs doesn’t look right:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function* (current)
vs
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/generator_function (proposed)

In Github comments it doesn’t create proper auto link for /funtion* had to wrap the URL in < > to not link it to /funtion. There could be other such drawbacks of using symbols in URLs. 🤔

It will be a massive change which may not happen easily. :(

[bsmth]

Just circling back to this one, I'd like to put a +1 on renaming the files to remove the parentheses from at least the file path so that we resolve issues such as this one: mdn/content#23602. With so few changes needed, I think it's worth it.

[bsmth]

I think most of this has been resolved by renaming, there's a pending Yari PR for the filechecker that can be found here: mdn/content#23605

[OnkarRuikar]

• enhance(filecheck): validate all file paths for lowercase and special characters yari#8019