Revamp the web site

[desruisseaux]

The current http://www.geoapi.org/ web site is generated by Maven. It is more Java focused than what we want GeoAPI to be and distracts users with a lot of information of low interest. We should abandon the Maven site plugin and revamp the web site. A proposal is to have at least the following hierarchy:

• www.geoapi.org/web/ for links to OpenAPI work done elsewhere at OGC.
• www.geoapi.org/java/ for Java API.
• www.geoapi.org/python/ for Python API.

Another goal is to have a clearer separation between what is in the released version and what is under development. All documentation about work in progress should be in the snapshot directory (or any other name making clear that this is not a release). Example of material that should move there is the documentation about geoapi-conformance.

A prototype to be presented at OGC meeting in Toulouse can be viewed there:

• https://geomatys.github.io/geoapi/

[kinow]

+1 for revamping the site. The proposed site looks simpler and less distracting. Maybe the layout could be improved to look a little more modern. e.g. OpenNLP site, Jupyter, QGIS.

Having a responsive layout for both desktop and mobile, and preferably addressing accessibility from the beginning (Firefox has a great accessibility tool, tweaking the new site colors and fonts to pass its checks can be helpful to lots of users).

[desruisseaux]

Thanks. For layout and look improvements I would need volunteer help. I will try to complete content first, and hope for some community action to emerge later.

[kinow]

Thanks. For layout and look improvements I would need volunteer help. I will try to complete content first, and hope for some community action to emerge later.

I can help with that. Will use the example above to build a couple tentative layouts and see what others think :+1:

[desruisseaux]

New site has been pushed on gh-pages branch. The site on Geomatys fork will be deleted. The commits have been rebased, so if anyone did a clone from Geomatys repository, they will need to do a git pull --force for pulling from OGC repository.

We still have do fix some broken links to geoapi-pending in the javadoc before to close this task. Those links should not have existed anyway.

[kinow]

Started working on a new layout as example this weekend, but it will take a bit longer to have something to show here.

I noticed that the gh-pages content is pure HTML. But there are parts of the layout that can be re-used. For example, the menu on the left, the header, the footer, and the content area. The content area being different for each page.

Normally this is handler by some tool like a static site generator, or with a dynamic site in php/js/python/etc. I think as we will host on GitHub, using a static site generator should be fine?

As for static site generators, Jekyll is supported out of the box in GitHub, meaning we wouldn't need to deploy or run any commands. But there are lots of other static site generators as good as Jekyll. Any preference?

[desruisseaux]

I have no preference on my side given that I'm not familiar with any static generator. Since Jekyll is supported by GitHub, it seems a natural choice. Actually I tried to use Jekyll at first, but have not been able to understand its working in the short time before OGC meeting.

[kinow]

Hi @desruisseaux before I do any more work, could you take a look at this preview please? https://kinow.github.io/geoapi-site/

It's using Jekyll and Tailwind CSS. Links probably broken, as I just wanted to put the general layout idea in place.

Any thoughts? What should change, what should stay, what should go? The mobile version should work, except the menu that is missing some JS code. But the elements should be correctly resized/repositioned.

Cheers Bruno

[desruisseaux]

Hello @kinow. Thanks for this work, its look good! Below is a few remarks, I do not know if they are known issue:

• The menu on the left is quite narrow on my browser (Firefox) - I can see only about half of the text.
• There is a lot of empty margin on both side; about half of the screen is empty. Is it desired? (I do not have a strong opinion on this matter at least when the amount of text is small anyway).
• Do we want to keep the banner on top?

Thanks! Martin

[kinow]

The menu on the left is quite narrow on my browser (Firefox) - I can see only about half of the text.

I'll have a look. I use Firefox too, but will test in another computer and try to tweak it.

There is a lot of empty margin on both side; about half of the screen is empty. Is it desired? (I do not have a strong opinion on this matter at least when the amount of text is small anyway).

I wonder if that's the resolution perhaps. I have a larger monitor at $work. Will take a look and try to adjust the margins.

Do we want to keep the banner on top?

Yup, but I had a bit of problem with that. Ideally, we would have a banner and a logo. Then position them as necessary.

But from looking at the old site git branch, I found only the single image with both. Would you have the separate files for each image?

Thanks!!!!

[kinow]

The menu on the left is quite narrow on my browser (Firefox) - I can see only about half of the text.

Fixed, it was getting the wrong CSS URL. It worked locally, but on github it had the extra base path (which I didn't test after pushing, sorry).

But from looking at the old site git branch, I found only the single image with both. Would you have the separate files for each image?

Oh, actually just found the logo file. But looks a bit different than the other one. The font size is smaller. Also, had to change the background to a lighter color due to the current logo's colors/tones.

logo - https://github.com/opengeospatial/geoapi/blob/gh-pages/snapshot/python/static/logo.png

URL to test again: https://kinow.github.io/geoapi-site/

And if the URL uses the cache, and the browser or server refuse to give a new version, I use this little trick sometimes (not only with jekyll sites): https://kinow.github.io/geoapi-site/?v=1, then just increment the v parameter, or use any random word. That normally avoids the browser/server caches.

[desruisseaux]

The site looks great, thanks!

The banner images are there: https://github.com/opengeospatial/geoapi/tree/gh-pages/images (sorry for having been slow to reply)

[kinow]

Thanks @desruisseaux ! :tada: glad we are going in the right direction. This way we shouldn't take too long to have a PR.

The banner images are there: https://github.com/opengeospatial/geoapi/tree/gh-pages/images (sorry for having been slow to reply)

I will try to add the banner image to the top, but that may be a bit tricky for mobile & desktop. Would you have other sources for it? Maybe a SVG, or GIMP file that I can modify or extract resources?

Oh, another thing, about the footer, there's a space for external links. I have an example with Twitter. Do you have any useful links for that part? Otherwise I'll just remove it.

[desruisseaux]

I do not have a SVG version of the logo. This logo is actually about 15 years old and I'm not sure who was the author. But it is not really required to keep it if impracticable for mobile devices.

For the link in the footer, I suggest to remove it. A link could have been OGC, but the copyright notice is already a link to OGC.

[kinow]

Finished the pages for all the links in the landing page. There are other links that are still missing/broken, but will keep adding them over the next days.

The only major challenge now is to add the special menu that is added per page. For example, when a user navigates to the Python section, there is a different menu for Python. There could be other ways to organize the site navigation, but I think it will be easier to focus just on the new layout first. Then decide what to do about menus later.

Let me know if there's anything that needs changing: https://kinow.github.io/geoapi-site/

Do we have a favicon for the site? It looks like we don't have one yet, but asking just in case.

Cheers Bruno

[desruisseaux]

Hello Bruno. Its look great! I presume that the source is at https://github.com/kinow/geoapi-site is that right? (the amount of commits is impressive!) So if I understood correctly, the HTML files became MD files but with the same HTML inside (minus header and footer). It looks all right to me.

There is no favicon for the site; I do not know how to do that actually.

Thanks!

[kinow]

Hello Martin

ts look great! I presume that the source is at https://github.com/kinow/geoapi-site is that right? (the amount of commits is impressive!)

Thanks! I am working there whenever I have spare time. Then once it is done will prepare a single commit for this repo as a PR. I am afraid it will be a huge commit.

So if I understood correctly, the HTML files became MD files but with the same HTML inside (minus header and footer). It looks all right to me.

Exactly. There will be a few differences in parts of the html as this new layout is using tailwindcss. But I am trying to keep things as simple as possible.

There is no favicon for the site; I do not know how to do that actually.

Got it. I will leave it without one and try to use the existing logo to create a favicon with GIMP later. (There are sites online that create favicons ico from common images too).

Thanks!

[kinow]

Hi @desruisseaux would you like to take a look before I prepare a pull request?

https://kinow.github.io/geoapi-site/

It took way longer than I expected, but I managed to get most of the old site working the same with jekyll and tailwindcss.

There is now a menu that changes depending on the entry. So if you navigate to the Java section, the menu will gain a few more entries specific to the Java API. Issues & notes:

• This submenu or pagemenu, works by identifying the existing menu entries and trying to match the first entry of the page menu against it. For example, if you navigate to "Developments", there is a submenu specifically for this section, so we append the menu under the existing section. The "Java" section, however, has no entry in the menu, so we append a new submenu under the existing menu.
• The menu should work on mobile, but it has the bare minimum to work. In the future I hope to have more spare time to work on a better menu for mobile interface.
• The archives section had a URL like geoapi.org/1.0, geoapi.org/2.0, etc. But in order to group submenu/pagemenu's, I had to include a base path in in the URL. So the old URLs for changes/history were moved to /changes/1.0, /changes/2.0. I think this is the only URL that was moved.
• There are some entries that go to a 3rd level. If you click on Java (1st level), we append the menu to the bottom of the existing menu. Then if you click on Examples, in the old site the menu is replaced by another menu specific to the Java examples. The current approach is limited to two levels only. The links are still accessible in the page, so I wonder if that's good enough for now?
• I've updated the README with some extra instructions, but didn't test if the old scripts are still working fine.

Finally, there is some learning curve for Jekyll & its new syntax. You can use Markdown or HTML. Some pages have an YAML header. That's called front matters in Jekyll.

The YAML is used to specify things like layout, variables to be used in the page, page title, etc. It is accessible to the page/template as page.

The contents of config.yml are available as site in the page/templates.

And the name of the syntax used in Jekyll templates is Liquid, created by Shopify.

We can also use Jekyll plugins, but if we add a plugin that is not available in GitHub pages, then we have to manually build the site, and push to a branch served by github pages. This new theme, for now, uses only the basic jekyll plugins. So once you push to github, GitHub will understand that's a Jekyll site and build in their infrastructure (with ruby, etc) and re-deploy the site. That may take some seconds or a couple of minutes.

Cheers Bruno

[kinow]

Almost forgot. I'm not completely happy with the logo. Tried changing it in GIMP but the resolution of the image is too small, so it got weird when I tried to increase the text. Converting it to SVG would be a good improvement for later.

Finally, I did a basic accessibility check with Firefox for contrast and basic issues. Changed some colors and font colors to pass the check.

There are other tools for color blindness and visual impairment that detect other issues, but alas I won't have time to complete it now (but will revisit it later :)

[desruisseaux]

Hello @kinow , this is excellent work, way above my competence! The site looks great to me. I browser through all links and it seems very complete. A few minor notes:

• In _pages/changes/2.3/index.md we apparently need to remove the /changes component of the path in the links (e.g. <td><a href="../2.3-M6/since-M5.html">M5</a></td>) in order to avoid broken links.
• The SVG icon for external links is well visible in the home page and in the menu, but seems invisible in the other pages.
• (Very minor) Maybe a slightly larger menu would allow "Development > Python API preview" to appear on a single line?

I think it is fine to have change pages moved to a changes directory. Maybe we should rename that directory as archives?

Thanks for your hard work!

[kinow]

Hi @desruisseaux

Thanks for testing it.

In _pages/changes/2.3/index.md we apparently need to remove the /changes component of the path in the links (e.g. M5) in order to avoid broken links.

Ah, good catch. That was a copy-and-paste accident I think. Fixed.

The SVG icon for external links is well visible in the home page and in the menu, but seems invisible in the other pages.

I used the URL /assets/.../externalLink.svg link. But on my page it's hosted under /geoapi-site/assets/.... Fixed by using another relative URL. Should be fixed now.

(Very minor) Maybe a slightly larger menu would allow "Development > Python API preview" to appear on a single line?

Tried changing how the width of menu and content are calculated. Could you take a look if that looks better now?

I think it is fine to have change pages moved to a changes directory. Maybe we should rename that directory as archives?

Done. Hopefully I didn't forget any URL.

Let me know if there's anything that needs changing :slightly_smiling_face: and thanks again for testing it so quickly.

Cheers Bruno

[desruisseaux]

Just had a look, and everything seem fine to me. Thanks!

[kinow]

So will prepare a pull request in the next hours/days :+1:

[desruisseaux]

Merged, thanks you very much for all your hard work! I'm closing this issue now; I think next evolutions can be subjects of new tasks if needed.

[kinow]

Thank you for your help Martin. I found one issue when the site is viewed from mobile, due to my last changes in the menu proportion.

I will start another branch later this weekend, and also star working on a better accessibility check.

That should give us time to gather any feedback from other users, which I can include in the next PR too.

Cheers Bruno

[desruisseaux]

No problem, take yours time and thanks again!