Best Practices for Writing .md

Link URLs

All links to a dox page ending without a trailing slash (eg. /open-source/victory) have a 302 redirect to the page with a trailing slash (eg. /open-source/victory/). It is ideal to link to the dox page with the trailing slash.

Base href

If a static site has <base href="{path}" />, relative links that work when viewing .md files on Github will not work on the static site. When the base element is on a page, anchor links and relative links no longer behave the same as Github. To fix it, we have to customize how marked or markdown-it generate the links so that we can prefix relative links with the base path.

So, we should keep writing markdown files exactly the same as we have been so that they continue to work on Github, but we'll just need to make sure we're transforming them properly if a site has a base href.

See the example in radium-docs.