search

ecohealthalliance / eha-ma-handbook

EcoHealth Alliance Modeling & Analytics Handbook
https://ecohealthalliance.github.io/eha-ma-handbook/
4 stars 11 forks source link

Add warning to contribution chapter about breaking URLs #44

Open collinschwantes opened 2 years ago

collinschwantes commented 2 years ago

Bookdown chapter URLs include the chapter number. When you add a chapter to any position except n+1 (appending it to the end) it will change the urls of other chapters. This can cause links to break, especially links outside the book.

We may want to consider using split_by: "rmd" when rendering html. This will break all links outside the book because it will remove the chapter numbers from the URLs. Going forward users will be able to insert chapters at any position without breaking links. Additionally, it should make it easier to setup redirects should we decided to change a chapter name.

mpadge commented 2 years ago

If it helps, the source code for https://devguide.ropensci.org has good examples of chapter links that don't break like that

collinschwantes commented 2 years ago

Following the devguide example would require us to switch to bookdown_bs4 for rendering.

mpadge commented 2 years ago

The general linking system is independent of bs4; that just allows some extra handlebars-type smart-linking. But chapter numbering is all automatic regardless, and all links works even when new chapters are inserted between any others. But i'm not exactly sure of the nature of your issue here, so may have misunderstood?

collinschwantes commented 2 years ago

The issue is that with our current settings, the URLs for chapters contain a chapter number like this https://ecohealthalliance.github.io/eha-ma-handbook/1-Contributing.html. If I add a chapter in the first position, the url would change to https://ecohealthalliance.github.io/eha-ma-handbook/2-Contributing.html and any references to that chapter using the full URL will break.

By using bs4 or split_by:"rmd" the URL for the contribution chapter becomes https://ecohealthalliance.github.io/eha-ma-handbook/Contributing.html, similar to what we observe in the RopenSci Dev guide.

Are redirects being handled somewhere else? Like if we were to change a chapter name from Contributing to Contributions does ROpenSci have a method for handling that?

mpadge commented 2 years ago

Redirects are mysteriously handled by netlify, so we don't have to worry and they never seem to fail? Or maybe they're handled before that by GitHub. Either way, they are definitely outsourced, and just magically work. Not that that helps you much :smirk: