Consistent URL slug style for documentation pages

[bajtos]

At the moment, the documentation files in docs/site are using different ways for creating URL slugs (filename-like parts of the URL path).

• Most files use Sentence-style.html format, especially those on the first level (docs/site/{name}.md):

  https://github.com/strongloop/loopback-next/blob/ae6427322451c914ae54f44dbb656981e7fbbb81/docs/site/Application.md#L6

• Nested files typically use directory-lowercase-style.md, where the slug combines the path element with the title in all lowercase:

  https://github.com/strongloop/loopback-next/blob/ae6427322451c914ae54f44dbb656981e7fbbb81/docs/site/migration/datasources.md#L7

• Some files use _ instead of - as the separator:

  https://github.com/strongloop/loopback-next/blob/ae6427322451c914ae54f44dbb656981e7fbbb81/docs/site/deployment/Deploying_to_ibm_cloud_kubernetes.md#L8

Personally, I'd like to use nested paths in URLs, e.g. /doc/en/lb4/migration/models/overview.html. I encountered some issues with that approach the last time I tried it, but I didn't investigate them deeper.

Let's discuss what URL style(s) we want to use in our docs and ideally come up with a single style to use consistently everywhere. @raymondfeng @hacksparrow @achrinza @strongloop/loopback-maintainers

[bajtos]

Important: it's easy to preserve old URLs to keep working as redirects to new paths, the trick is to add redirect_from to front-matter:

-permalink: /doc/en/lb4/Using-database-transactions.html
+permalink: /doc/en/lb4/data-access-guides-transactions.html
+redirect_from: /doc/en/lb4/Using-database-transactions.html

[raymondfeng]

1. I would prefer to have to file names and urls to use snake style:

   • application.md => application.html
   • openapi-generator.md => openapi-generator.html

2. We need to understand the impact of renaming existing urls as it may break existing references

3. We should also have more structures for docs/site - by moving some files into child directories

4. IIRC, using nesting paths in html urls caused some problems in Jeykyll rendering of sidebars.

[jannyHou]

Facing similar problem in https://github.com/strongloop/loopback-next/pull/6085 Agree with using snake style and -