Re: Canonicalization of URLs on our website
Hi all, On Sun, 21 Apr 2024 at 20:19, Volkan Yazıcı 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
Re: Canonicalization of URLs on our website
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 wrote: > Hi all, > > On Sun, 21 Apr 2024 at 20:19, Volkan Yazıcı 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 >
[VOTE] Release Apache Log4j Tools `0.9.0`
This is a vote to release the Apache Log4j Tools `0.9.0`. Website: https://logging.staged.apache.org/log4j/tools-0.9.0 GitHub: https://github.com/apache/logging-log4j-tools Commit: 9d822d3a7daa5e1e6a953b66ff12e4b87b99ef7e Distribution: https://dist.apache.org/repos/dist/dev/logging/log4j-tools/0.9.0 Nexus: https://repository.apache.org/content/repositories/orgapachelogging-1284 Signing key: 0x077e8893a6dcc33dd4a4d5b256e73ba9a0b592d0 Please download, test, and cast your votes on this mailing list. [ ] +1, release the artifacts [ ] -1, don't release, because... This vote is open for 72 hours and will pass unless getting a net negative vote count. All votes are welcome and we encourage everyone to test the release, but only the Logging Services PMC votes are officially counted. At least 3 +1 votes and more positive than negative votes are required. == Review kit The minimum set of steps needed to review the uploaded distribution files in the Subversion repository can be summarized as follows: # Check out the distribution svn co https://dist.apache.org/repos/dist/dev/logging/log4j-tools/0.9.0 && cd $_ # Verify checksums shasum --check *.sha512 # Verify signatures wget -O - https://downloads.apache.org/logging/KEYS | gpg --import for sigFile in *.asc; do gpg --verify $sigFile; done # Verify reproduciblity umask 0022 unzip *-src.zip -d src cd src export NEXUS_REPO=https://repository.apache.org/content/repositories/orgapachelogging-1284 sh mvnw -Prelease verify artifact:compare -Dreference.repo=$NEXUS_REPO # If preferred, augment `mvnw` with `-DskipTests` to speed things up == Release notes This minor release contains small bug fixes and improvements. === Added * Add `skip` parameter to all Maven goals (#121) * Support multiple index and type templates in the `log4j-docgen:generate-documentation` configuration (#122) === Changed * Website is migrated to Antora (apache/logging-log4j2#2443) === Fixed * Fix handling of subclassed plugins in Log4j Docgen (#120) === Updated * Update `commons-io:commons-io` to version `2.16.1` (#114) * Update `org.apache.logging:logging-parent` to version `11.0.0` (#115) * Update `org.apache.maven.plugin-tools:maven-plugin-annotations` to version `3.13.0` (#118) * Update `org.codehaus.modello:modello-maven-plugin` to version `2.4.0` (#119) * Update `org.xmlunit:xmlunit-assertj3` to version `2.10.0` (#116)
Re: Canonicalization of URLs on our website
Volkan, I completely agree with you. I prefer to review my site changes either in target/site or by doing a deploy to a local directly. In both cases I use the file protocol to view it. Ralph > On May 8, 2024, at 5:55 AM, Volkan Yazıcı wrote: > > 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 > wrote: > >> Hi all, >> >> On Sun, 21 Apr 2024 at 20:19, Volkan Yazıcı 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 >>
Re: Canonicalization of URLs on our website
Hi Volkan, On Wed, 8 May 2024 at 14:57, Volkan Yazıcı wrote: > 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. If we use a non-default `html_extension_style`, you can still preview the website locally. You just need to modify the Antora Playbook (AFAIK Antora does not support variable substitution in the playbook). We can also set `html_extension_style: default` in our Git repo and configure the CI to modify it when it builds the staging site. I usually use my IDE to preview the documentation pages, so for me it is not a problem. Anyway I value consistency more than one particular solution. If we prefer to stick with the `default` style, for SEO purposes we should ensure that all our internal links end up in `.html`. This mainly applies to index files. Piotr
Re: Canonicalization of URLs on our website
The IDE lets you view the page you are editing but generally it doesn’t show you the nav or the rest of the site. I am also not confident that everything will be styled exactly the same as it will appear in the browser. So, in short, the IDE is great for editing but I like to do my reviews on a local site. Ralph > On May 8, 2024, at 9:50 AM, Piotr P. Karwasz wrote: > > Hi Volkan, > > On Wed, 8 May 2024 at 14:57, Volkan Yazıcı wrote: >> 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. > > If we use a non-default `html_extension_style`, you can still preview > the website locally. You just need to modify the Antora Playbook > (AFAIK Antora does not support variable substitution in the playbook). > We can also set `html_extension_style: default` in our Git repo and > configure the CI to modify it when it builds the staging site. > > I usually use my IDE to preview the documentation pages, so for me it > is not a problem. > > Anyway I value consistency more than one particular solution. If we > prefer to stick with the `default` style, for SEO purposes we should > ensure that all our internal links end up in `.html`. This mainly > applies to index files. > > Piotr
