On Wed, 8 Sep 2021 15:57:58 GMT, Erik Joelsson <er...@openjdk.org> wrote:
> I don't think just changing the link here is the correct action. +1. Let's not do this change yet. > 1. Create two links and mark them with .md and .html so that the reader > may pick the one that makes sense depending on context. > 2. Get rid of the html files since Github now naturally uses .md files > rather than .html files for online reading. > 3. Do nothing and continue to consider the html files as the official > online documentation files. > > I'm thinking 2 may be the preferred action, but would like more input from > others. (2) looks appealing for me, for a different reason: if you regenerate `.md` -> `.html`, and choose the unexpected pandoc version (for example one provided by distro), then `.html` diff would have a lot of fluff not related to the actual change. And that would keep happening as people regenerate `.html` with their own versions of pandocs :) Removing `.html` from repo resolves this problem at its core. We can still rewire `make update-build-docs` to e.g. `make generate-build-docs` and put the resulting HTML to `build/` somewhere, so whoever deploying the HTML files on their site can still get it easily. ------------- PR: https://git.openjdk.java.net/jdk/pull/5417
