Do we need to restore page html suffix to documentation pages?

[jodygarnett]

Describe the bug

Forwarding from the old manual was supposed to be possible and the intension was to have the new pages be the same (complete with html suffixes) so forwarding would be easy.

The pages for the documentation have been generated as folders:

• https://docs.geonetwork-opensource.org/4.2/user-guide/quick-start/

Expected behaviour

When proposing mkdocs I had tested the command line mkdocs build --no-directory-urls option to confirm we could generate html pages.

I expected:

• https://docs.geonetwork-opensource.org/4.2/user-guide/quick-start/index.html
• https://docs.geonetwork-opensource.org/4.2/user-guide/describing-information/creating-metadata.html

With the goal of allowing URL forward rules to be handled for older clients:

• https://geonetwork-opensource.org/manuals/3.12.x/en/user-guide/quick-start/index.html
• https://geonetwork-opensource.org/manuals/3.12.x/en/user-guide/describing-information/creating-metadata.html

Additional context

The github workflow uses mike to handle publication to gh-pages branch, it is unclear if mike supports configuration or command line option to control how content is generated.

• https://github.com/geonetwork/core-geonetwork/blob/main/.github/workflows/docs.yml

[jodygarnett]

I cannot find a suitable command line or configuration option yet for mike.

I am going to ask: https://github.com/jimporter/mike/issues/204

[jodygarnett]

Of course the moment I ask for help the configuration option is revealed use_directory_urls

@josegar74 it is up to you if you wish to go ahead with this change, I am sorry this was not caught during earlier review cycle.

[josegar74]

@jodygarnett what we understood in the original pull request, it was that MkDocs didn't support the html pages.

The change you propose is fine, but we need to revert also the changes that were applied to https://github.com/geonetwork/core-geonetwork/blob/main/web/src/main/webapp/WEB-INF/data/data/resources/config/manual.json

Users that doesn't update to the latest version will have problems to access the manual, but it will have an easy solution, updating to the latest version.

[jodygarnett]

It is up to you to consider what is nicest, should consider if URL forwarding can be setup cleanly (that is a good point for html suffix).

If not the short url syntax is nicer for users.

[jodygarnett]

Some research - the goal of this is really to ensure google search results find the current docs:

1. websearch geonetwork administrator guide

   Returns: https://geonetwork-opensource.org/manuals/3.12.x/en/administrator-guide/index.html

2. This should forward to 3.12 docs:

   https://docs.geonetwork-opensource.org/3.12/administrator-guide/

3. Testing now https://docs.geonetwork-opensource.org/3.12/administrator-guide/index.html also works.

   So perhaps forward can work without further change.

4. Version changer at the top did not remember page when chaning to 4.4 Latest

   https://docs.geonetwork-opensource.org/4.4/administrator-guide/

   Checking details we should stay on the same page as we configure [site_url] correctly.

[jodygarnett]

@juanluisrp this decision is going to be based on what can be accomplish with http redirect from https://geonetwork-opensource.org/manuals/3.12.x/en/administrator-guide/index.html to https://docs.geonetwork-opensource.org/3.12/administrator-guide/

Can we have redirect to

• RULE1: https://geonetwork-opensource.org/manuals/3.12.x/en/{path}/index.html --> https://docs.geonetwork-opensource.org/3.12/{path}/
• RULE2: https://geonetwork-opensource.org/manuals/3.12.x/en/{page_path}.html --> https://docs.geonetwork-opensource.org/3.12/{page_path}/
• Similar for fr index.html
• Similar for fr .html

[jodygarnett]

@juanluisrp this needs your attention before it can be unblocked.

[juanluisrp]

So far I've added these rules:

	# Redirection for URLs with language "en"
	RewriteRule ^/?manuals/(\d+.\d+).x/en/index.html$ https://docs.geonetwork-opensource.org/$1/ [R=301,L]
	RewriteRule ^/?manuals/(\d+.\d+).x/en/(.*)/index.html$ https://docs.geonetwork-opensource.org/$1/$2/ [R=301,L]
	RewriteRule ^/?manuals/(\d+.\d+).x/en/(.*).html$ https://docs.geonetwork-opensource.org/$1/$2/ [R=301,L]

	# Redirection for URLs with language other than "en"
	RewriteRule ^/?manuals/(\d+.\d+).x/([a-z]{2})/index.html$ https://docs.geonetwork-opensource.org/$1/$2/ [R=301,L]
	RewriteRule ^/?manuals/(\d+.\d+).x/([a-z]{2})/(.*)/index.html$ https://docs.geonetwork-opensource.org/$1/$2/$3/ [R=301,L]
	RewriteRule ^/?manuals/(\d+.\d+).x/([a-z]{2})/(.*).html$ https://docs.geonetwork-opensource.org/$1/$2/$3/ [R=301,L]

Still pending the rules for 2.x.y versions. Currently they have:

	# Redirect old 2.x.y versions to 2.10.4
	RewriteCond %{REQUEST_URI} !^/manuals/2\.10\.4/
	RewriteRule ^/manuals/2\.[0-9]+\.[0-9]+/(.*)$ /manuals/2.10.4/$1 [R=301,L]
        RewriteRule ^/manuals/trunk/(.*)$ /manuals/3.12.x/$1 [R=301,L]

And they need to be updated to the new location at https://docs.geonetwork-opensource.org/

[juanluisrp]

Added these new rules to manage /manuals/2.x.y and /manuals/3.x.y/$LANG/users/ paths:

        # Redirect old 2.10.4 to new github pages. Needs to remove the language
        RewriteRule ^/?manuals/2.10.4/[a-zA-Z]{2,3}/index.html$ https://docs.geonetwork-opensource.org/2.10/ [R=301,L]
        RewriteRule ^/?manuals/2.10.4/[a-zA-Z]{2,3}/(.*)/index.html$ https://docs.geonetwork-opensource.org/2.10/$1/ [R=301,L]
        RewriteRule ^/?manuals/2.10.4/[a-zA-Z]{2,3}/(.*).html$ https://docs.geonetwork-opensource.org/2.10/$1/ [R=301,L]

        # Redirection of /manuals/3.12.x/eng/users/ to /manuals/3.12.x/en/
        RewriteRule ^/?manuals/(3.\d+).x/eng/users/(.*)$ /manuals/3.12.x/en/$2 [R=301,L]
        RewriteRule ^/?manuals/(3.\d+).x/fra/users/(.*)$ /manuals/3.12.x/fr/$2 [R=301,L]

Some test URLs:

• https://www.geonetwork-opensource.org/manuals/2.10.4/eng/developer/release/index.html -> https://docs.geonetwork-opensource.org/2.10/developer/release/
• https://www.geonetwork-opensource.org/manuals/2.10.4/eng/developer/xml_services/index.html -> https://docs.geonetwork-opensource.org/2.10/developer/xml_services/

[jodygarnett]

Marking this as resolved, we did not need html suffix. And rewriting works.