With the docs being moved to a section at https://mapzen.com/documentation/mobility/ for all of mobility (rather than separate sections for Turn-by-Turn, Matrix, and Optimized route like we had before), there was a lot of custom work with our publishing process to make sure that files were renamed and old URLs redirected.
It's become clearer that we should do these changes upstream in the source files, rather than as part of the publishing process. For example, because of the valhalla-docs file structure and redirecting that has to happen to build the mobility help, we are no longer able to use relative links between files within the same mobility section because they do not forward properly. We have to link with the full, hard-coded URL to link within the mobility help.
I believe it is OK to reorganize the content as it is displayed in GitHub, as we have made no promises for stable links there, and anyone with bookmarks should be able to figure out the new location.
[x] rename optimized_route to optimized. We are doing the renaming on the publish.
[x] move the loose, root-level md files for Turn-by-Turn into a folder named turn-by-turn. We are forwarding these right now on the output so they will have the same URL structure as the other services in mobility.
With the docs being moved to a section at https://mapzen.com/documentation/mobility/ for all of mobility (rather than separate sections for Turn-by-Turn, Matrix, and Optimized route like we had before), there was a lot of custom work with our publishing process to make sure that files were renamed and old URLs redirected.
It's become clearer that we should do these changes upstream in the source files, rather than as part of the publishing process. For example, because of the valhalla-docs file structure and redirecting that has to happen to build the mobility help, we are no longer able to use relative links between files within the same mobility section because they do not forward properly. We have to link with the full, hard-coded URL to link within the mobility help.
I believe it is OK to reorganize the content as it is displayed in GitHub, as we have made no promises for stable links there, and anyone with bookmarks should be able to figure out the new location.