All non-default `html_extension_style` options require to run a web server.
In my opinion, - Being able to view `target/site` with just using my browser and nothing else is super convenient. The development experience is much smoother. - None of the advantages you cited for switching from `/foo.html` to `/foo`, `/foo/index.html`, etc. is worth the trouble/complexity it will introduce. In short, I am not inclined to change the current path naming scheme. That said, I don't want to sound bossy. I would appreciate it if others can join the discussion with their arguments. On Wed, May 8, 2024 at 10:22 AM Piotr P. Karwasz <piotr.karw...@gmail.com> wrote: > Hi all, > > On Sun, 21 Apr 2024 at 20:19, Volkan Yazıcı <vol...@yazi.ci> wrote: > > 1. Could you show us the Antora configuration option you mentioned > > and how we can use it to achieve what you propose? > > I found the perfect Antora setting: `html_extension_style`[1]. > > The option I am proposing corresponds to the `drop` style: > > * a `/foo/bar.html` file will be referenced as `foo/bar`, > * a `/foo/index.html` file will be referenced as `foo/`. > > The `indexify` style is very similar, but it always uses a trailing > `/` for the file names. > > I see both pros and cons for the two styles: > > ## `indexify` style > > Pros: > * Doesn't make a difference between "normal" HTML files and folders. > If we transform `foo.html` into `foo/index.html` and add subpages, the > URL remains always `foo/`. > * We restore the old URLs like `/log4j/2.x/log4j-api/` that became > `/log4j/2.x/log4j-api.html`. > * Works on every HTTP server (even Python's). > > Cons: > * We need a lot of HTTP redirects like > `/log4j/2.x/manual/configuration.html` -> > `/log4j/2.x/manual/configuration/` > > ## `drop` style > > Pros: > * We don't need redirects for the current pages, only a global rewrite > rule that states that we prefer to omit the `.html` suffix. > * It is shorter than the `indexify` style. > * It is easier to implement on already compiled pages: no need to > move/rename files. > > Cons: > * If `foo.html` becomes `foo/index.html` the canonical URL changes > from `foo` to `foo/`. However the redirect from the old to the new URL > is done automatically by most servers. > * It doesn't work with all web servers, but it works with Apache HTTP > Server. > > What do you think about adopting the `drop` style? > > Piotr > > PS: Javadoc also can use the `drop` style. See e.g. Jakarta drops the > `.html` (and apparently capital letters) from its Javadoc. > > [1] > https://docs.antora.org/antora/latest/playbook/urls-html-extension-style/ > [2] > https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/filter >
