Separate URL paths from code structure

[RobinBrinkmann]

The URL path of the documents are currently based on structure and naming of the github repo. In order to improve navigation within the repository, we numbered the group of files according to their order on the page. This leads to links that are harder to read, especially when copied/pasted (3 - Development -> 3%20-%20Deployment).

We would like to separate the displayed URL paths from the naming / code path. A solution could be o configure collections:
https://pmarsceill.github.io/just-the-docs/docs/configuration/#document-collections

[weberjm]

After review of the collections and of Jekyll base linking behavior, all behaviors would have impacts on "ease of use."

• One method of updating the permalinks for each page is to use a standard permalink behavior. However, this link behavior cannot use the parent page or folder, so each page will have to have its link written out completely. Ex: permalink: /BasicConcepts/ComponentsBasics in the file "docs > 1 - Basic Concepts > ComponentsBasics.md"
• Using the Collections feature, if we create one Collection for "docs," then the generation process would use the folder names as it does now to create links for each page. If we create multiple Collections, then the overall directory structure would have to be changed around anyway, with /docs becoming the "collections folder" and each collection having a folder matching the Collection name: /docs/_basic_concepts
• If we simply remove the spaces from the folder names in Github, then we will avoid the HTML encoding problems listed above, and will only introduce minimal additions to the URL scheme. Additionally, by setting the permalink field in _config.yaml to ":basepath," we can also remove the trailing .html at the end of each file, providing additional cleanliness in the URL scheme.

As an additional note, Jekyll now supports linking to internal files via their pre-build page name, and will fail the build if there are broken links. This could be implemented to help prevent broken links with any future updates: https://jekyllrb.com/docs/liquid/tags/#links

[RobinBrinkmann]

Pushing this back to the icebox as we did not find a working solution so far.