Connect/Java: Refurbish landing page

Author: amotl

docs/_include/logos.md

@@ -0,0 +1,8 @@
+<!-- markdownlint-disable MD034 -->
+<!-- markdownlint-disable MD053 -->
+
+[CrateDB logo]: https://avatars.githubusercontent.com/u/4048232?s=200&v=4
+[Hibernate logo]: https://logo.svgcdn.com/devicon/hibernate-original.svg
+[jOOQ logo]: https://www.jooq.org/img/jooq-logo-black.png
+[JUnit logo]: https://avatars.githubusercontent.com/u/874086?s=200&v=4
+[PostgreSQL logo]: https://jdbc.postgresql.org/icons/postgreslogo.svg

docs/connect/java/index.md

@@ -5,85 +5,82 @@
 
 :::{include} /_include/links.md
 :::
+:::{include} /_include/logos.md
+:::
 
 :::{div} sd-text-muted
-Java applications mostly use JDBC to connect to CrateDB.
+Connect to CrateDB and CrateDB Cloud from Java.
 :::
 
-## Protocols
-
-### JDBC
+## JDBC
 
 :::{div}
-[JDBC] is a standard Java API that provides a common interface for accessing
+[JDBC] is the standard Java API that provides a common interface for accessing
 databases in Java.
 :::
 
 :::{rubric} Driver options
 :::
 
 :::{div}
-You have two JDBC driver options: The [PostgreSQL
-JDBC Driver] and the {ref}`crate-jdbc:index`.
+You have two JDBC driver options: The {ref}`postgresql-jdbc` Driver
+and the {ref}`cratedb-jdbc` Driver.
 PostgreSQL JDBC uses the `jdbc:postgresql://` protocol identifier,
 while CrateDB JDBC uses `jdbc:crate://`.
 :::
 
 You are encouraged to probe the PostgreSQL JDBC Driver first. This is the
 most convenient option, specifically if the system you are connecting with
-already includes the driver jar.
+already includes the PostgreSQL driver JAR file, and you can't change it.
 
 However, applications using the PostgreSQL JDBC Driver may emit PostgreSQL-specific
-SQL that CrateDB does not understand. Use the CrateDB JDBC Driver instead
+SQL that CrateDB does not understand, while the framework assumes the
+database would understand the PostgreSQL dialect completely.
+In this case, use the CrateDB JDBC Driver instead
 to ensure compatibility and allow downstream components to handle
 CrateDB-specific behavior, for example, by employing a CrateDB-specific
-SQL dialect implementation.
+SQL dialect implementation for their purposes and realms.
 
 The {ref}`crate-jdbc:internals` page includes more information
 about compatibility and differences between the two driver variants,
 and more details about the CrateDB JDBC Driver.
 
-### HTTP
-
-You can also talk to CrateDB using HTTP, using any HTTP library of your choice.
-Below is a quick example using Apache Commons HTTP.
-
-
-## Driver list
+:::{rubric} Adapters and drivers
+:::
 
 :::::{grid} 2 2 2 3
-:gutter: 3
+:gutter: 2
 :padding: 0
 
-::::{grid-item-card} {fab}`java;fa-xl` PostgreSQL JDBC
+::::{grid-item-card} ![PostgreSQL logo][PostgreSQL logo]{height=40px}   PostgreSQL JDBC
 :link: postgresql-jdbc
 :link-type: ref
 :link-alt: PostgreSQL JDBC (pgJDBC)
 The PostgreSQL JDBC driver.
 ::::
 
-::::{grid-item-card} {fab}`java;fa-xl` CrateDB JDBC
+::::{grid-item-card} ![CrateDB logo][CrateDB logo]{height=40px}   CrateDB JDBC
 :link: cratedb-jdbc
 :link-type: ref
 :link-alt: CrateDB JDBC
 The CrateDB JDBC driver.
 ::::
 
-::::{grid-item-card} {fab}`hibernate` Hibernate
+::::{grid-item-card} ![Hibernate logo][Hibernate logo]{height=40px}   Hibernate
 :link: hibernate
 :link-type: ref
 :link-alt: Hibernate with CrateDB
 A Quarkus/Panache example using Hibernate.
 ::::
 
-::::{grid-item-card} {fab}`jooq` jOOQ
-:link: hibernate
+::::{grid-item-card} ![jOOQ logo][jOOQ logo]{height=40px}   jOOQ
+:link: jooq
 :link-type: ref
 :link-alt: jOOQ with CrateDB
 A jOOQ example.
 ::::
 
-::::{grid-item-card} {fab}`junit` Software testing
+::::{grid-item-card} ![JUnit logo][JUnit logo]{height=40px}   Software testing
 :link: java-testing
 :link-type: ref
 :link-alt: Software testing with CrateDB and Java
@@ -92,7 +89,15 @@ JUnit and Testcontainers for CrateDB.
 
 :::::
 
-{material-outlined}`apps;2em`
+## HTTP
+
+You can also talk to CrateDB using HTTP, using any HTTP library of your choice.
+Below is a quick example using Apache Commons HTTP.
+
+:::{todo}
+Add example.
+:::
+
 
 :::{toctree}
 :maxdepth: 1