Normalize naming convention for docs

[etsauer]

Before our next docs release, I would like for us to normalize the file naming convention for our docs/ folder. Since the file and directory names drive the URL structure of the Pelorus website, I would like to propose the following conventions to start:

• All lowercase letters for files and directories
• Use hyphens (-) to separate words

[mpryc]

While doing the doc rework with @mateusoliveira43 we actually renamed all the files from kebab-case(spinal-case) to PascalCase format, except index.md, which has to be lower-case. But I don't have anything against reverting back to kebab-case for files, just this would need to be propagated in few other places where we have links already set / or create redirects to point to new locations.

[mpryc]

Here is nice write-up on the Geeks Culture site: https://medium.com/geekculture/markdown-best-practices-911be77a1282 as the other side of the medal another docs that recommends kebab-cases https://arcticicestudio.github.io/styleguide-markdown/rules/naming-conventions.html for GitHub flavored markdown.

[mateusoliveira43]

I agree with Eric on using snake-case (lowercase letters and hyphens to separate words) for the file and folders in the docs

But lets document that! (under development, maybe)

[mpryc]

@mateusoliveira43 snake_case_file_name.md or kebab-case-file-name.md ? @etsauer proposed second option so kebab-case

[mateusoliveira43]

sorry, my mistake. I prefer snake_case (because I am a Python guy hehehe), but I saw that people prefer kebab-case for URLs. To follow convention, I believe its better to use kebab-case

So, my vote is to name every markdown file in docs folder kebab-case (images I would use snake_case)

[mpryc]

So we have proposition for docs/** folder, except docs/img:

1. "Text" files such as: *.md / *.css, / *.htm* / *.txt:

   • a) All lowercase letters
   • b) Use hyphens (-) to separate words (kebab-case-file-name.ext)

2. Directory names, except sub-directories in the docs/img:

   • a) All lowercase letters
   • b) Use hyphens (-) to separate words (kebab-case-dir-name)

3. Image files *.png / *.jpg / *.jpeg / *.svg and subdirectory names in the docs/img:

   • a) All lowercase letters
   • b) Use underscore ( _ ) to separate words (my_image_name.ext) / (docs/img/my_image_subfolder)

@mateusoliveira43 @etsauer @KevinMGranger is that about right? Also what is best for 2b ?

[mateusoliveira43]

to make things simple, can we have everything (folders and files) under docs folder use kebab-case (except the files and folders in img folder)?

in this case, 2.b) would use hyphens (-) as well

[mpryc]

Sure we do, so updating the previous comment to have it a base for our development doc.

[mpryc]

@mateusoliveira43 updated, but this isn't simpler, see how the guideline looks now (docs/img/..) case is different then (docs/**), which make it harder imo.