Client versioning

contribute/style-guide.md

@@ -251,3 +251,55 @@ should pass. Finally open another PR on the docs repo again to remove the
 file from the exception list and add it to `sidebars.js` in the appropriate
 sidebar.
 
+## Client versioning
+
+Docusaurus supports versioning documentation, however it is opinionated and 
+aimed more at use cases where you have a single product with set releases, or
+multiple products with their own releases.
+
+Due to the fact that we have many 
+different integrations in ClickHouse, each of which may need versioned documentation,
+we use the following custom `ClientVersionDropdown` component for versioning of
+client documentation:
+
+```markdown
+<ClientVersionDropdown versions={}/>
+```
+
+To use this component, import it into the markdown page:
+
+```markdown
+import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown'
+```
+
+Add it underneath the H1 element on the page and pass it an array of objects
+representing versions and the slug of the page:
+
+```markdown
+# JDBC Driver (0.8+)
+
+<ClientVersionDropdown versions={[
+{
+'version': 'v0.8+',
+'slug': '/docs/integrations/language-clients/java/jdbc'
+},
+{
+'version': 'v0.7.x',
+'slug': '/docs/integrations/language-clients/java/jdbc-v1'
+}
+]}/>
+```
+
+Note that the component will display the first item as the 'selected' version, so
+it is important to make sure the order of the objects is correct.
+
+Add this component on every 'versioned' page for the client.
+
+In addition, add to every 'archived' version page the following frontmatter item:
+
+```markdown
+displayed_sidebar: integrations
+```
+
+This will make sure that the sidebar displays, even if this particular page is
+not shown in the sidebar.

docs/integrations/language-clients/java/client-v1.md

@@ -2,13 +2,26 @@
 title: 'Client (0.7.x and earlier)'
 description: 'Java client library to communicate with a DB server through its protocols.'
 slug: /integrations/language-clients/java/client-v1
+displayed_sidebar: 'integrations'
 ---
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import CodeBlock from '@theme/CodeBlock';
-
-# Client (0.7.x and earlier)
+import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown';
+
+# Java client (0.7.x and earlier)
+
+<ClientVersionDropdown versions={[
+{
+'version': 'v0.7.x',
+'slug': '/integrations/language-clients/java/client-v1'
+},
+{
+'version': 'v0.8+',
+'slug': '/docs/integrations/language-clients/java/client'
+}
+]}/>
 
 Java client library to communicate with a DB server through its protocols. Current implementation supports only [HTTP interface](/interfaces/http). The library provides own API to send requests to a server.
 

docs/integrations/language-clients/java/client.md

@@ -10,15 +10,23 @@ title: 'Java Client (0.8+)'
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import CodeBlock from '@theme/CodeBlock';
-
-# Java Client (0.8+)
+import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown';
+
+# Java client (0.8+)
+
+<ClientVersionDropdown versions={[
+{
+'version': 'v0.8+',
+'slug': '/docs/integrations/language-clients/java/client'
+},
+{
+'version': 'v0.7.x',
+'slug': '/integrations/language-clients/java/client-v1'
+}
+]}/>
 
 Java client library to communicate with a DB server through its protocols. The current implementation only supports the [HTTP interface](/interfaces/http). 
-The library provides its own API to send requests to a server. The library also provides tools to work with different binary data formats (RowBinary* & Native*).  
-
-:::note
-If you're looking for a prior version of the java client docs, please see [here](/integrations/language-clients/java/client-v1.md).
-:::
+The library provides its own API to send requests to a server. The library also provides tools to work with different binary data formats (RowBinary* & Native*).
 
 ## Setup {#setup}
 

docs/integrations/language-clients/java/index.md

@@ -12,7 +12,7 @@ import CodeBlock from '@theme/CodeBlock';
 # Java Clients Overview
 
 - [Client 0.8+](./client.md)
-- [JDBC 0.8+](./jdbc.md)
+- [JDBC 0.8+](./jdbc)
 - [R2DBC Driver](./r2dbc.md)
 
 ## ClickHouse Client {#clickhouse-client}

docs/integrations/language-clients/java/jdbc-v1.md

@@ -2,15 +2,27 @@
 title: 'JDBC Driver'
 description: 'Page describing the JDBC driver for ClickHouse'
 slug: /integrations/language-clients/java/jdbc-v1
+displayed_sidebar: 'integrations'
 ---
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import CodeBlock from '@theme/CodeBlock';
-
+import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown'
 
 # JDBC Driver
 
+<ClientVersionDropdown versions={[
+{
+'version': 'v0.7.x',
+'slug': '/docs/integrations/language-clients/java/jdbc-v1'
+},
+{
+'version': 'v0.8+',
+'slug': '/docs/integrations/language-clients/java/jdbc'
+}
+]}/>
+
 `clickhouse-jdbc` implements the standard JDBC interface. Being built on top of [clickhouse-client](/integrations/sql-clients/sql-console), it provides additional features like custom type mapping, transaction support, and standard synchronous `UPDATE` and `DELETE` statements, etc., so that it can be easily used with legacy applications and tools.
 
 :::note

docs/integrations/language-clients/java/jdbc.md

@@ -10,17 +10,24 @@ title: 'JDBC Driver (0.8+)'
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import CodeBlock from '@theme/CodeBlock';
-
+import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown'
 
 # JDBC Driver (0.8+)
 
+<ClientVersionDropdown versions={[
+{
+'version': 'v0.8+',
+'slug': '/docs/integrations/language-clients/java/jdbc'
+},
+{
+'version': 'v0.7.x',
+'slug': '/docs/integrations/language-clients/java/jdbc-v1'
+}
+]}/>
+
 `clickhouse-jdbc` implements the standard JDBC interface using the latest [java client](/integrations/language-clients/java/client.md).
 We recommend using the latest [java client](/integrations/language-clients/java/client.md) directly if performance/direct access is critical.
 
-:::note
-If you're looking for a prior version of the JDBC driver docs, please see [here](/integrations/language-clients/java/jdbc-v1.md).
-:::
-
 ## Changes from 0.7.x {#changes-from-07x}
 In 0.8 we tried to make the driver more strictly follow the JDBC specification, so there are some removed features that may affect you:
 

src/theme/ClientVersionDropdown/ClientVersionDropdown.js

@@ -0,0 +1,120 @@
+import React, {useState, useEffect, useRef} from 'react';
+import Link from '@docusaurus/Link';
+import styles from './styles.module.css'
+import ReactDOM from 'react-dom';
+import {useHistory} from "react-router-dom";
+
+const ClientVersionDropdown = (props) => {
+
+    const history = useHistory()
+    const [displayDropdown, setDisplayDropdown] = useState(false)
+    const [dropdownPosition, setDropdownPosition] = useState({top: 0, left: 0});
+    const buttonRef = useRef(null);
+    const dropdownRef = useRef(null);
+
+    const onClickHandler = () => {
+        setDisplayDropdown(!displayDropdown)
+    }
+
+    const handleLinkClick = (e, slug) => {
+        e.preventDefault();
+
+        // Navigate after a slight delay to ensure the click event completes
+        setTimeout(() => {
+            setDisplayDropdown(false);
+            history.push(slug);
+        }, 10);
+    };
+
+    // Calculate and update dropdown position when it's displayed
+    useEffect(()=> {
+        if (displayDropdown && buttonRef.current) {
+            const buttonRect = buttonRef.current.getBoundingClientRect();
+            setDropdownPosition({
+                top: buttonRect.bottom + window.scrollY,
+                left: buttonRect.left + window.scrollX
+            })
+        }
+    }, [displayDropdown])
+
+    // Close the dropdown menu when clicking outside
+    useEffect(()=>{
+        const handleClickOutside = (event) => {
+
+            if (dropdownRef.current && dropdownRef.current.contains(event.target)) {
+                if (event.target.tagName === 'A') {
+                    return;
+                }
+            }
+
+            // Otherwise close if clicked outside button or dropdown
+            if (buttonRef.current && !buttonRef.current.contains(event.target) &&
+                dropdownRef.current && !dropdownRef.current.contains(event.target)) {
+                setDisplayDropdown(false);
+            }
+        };
+
+        if (displayDropdown) {
+            document.addEventListener('mousedown', handleClickOutside);
+        }
+
+        return () => {
+            document.removeEventListener('mousedown', handleClickOutside)
+        }
+    }, [displayDropdown])
+
+    // Render dropdown menu in a portal
+    const renderDropdown = () => {
+        if (!displayDropdown) return null;
+
+        const dropdownStyleDynamic = {
+            top: `${dropdownPosition.top}px`,
+            left: `${dropdownPosition.left}px`,
+        };
+
+        return ReactDOM.createPortal(
+            <div
+                className={styles.dropdownStyleStatic}
+                style={dropdownStyleDynamic}
+                ref={dropdownRef}
+            >
+                {props.versions.map((item, index) => (
+                    <Link
+                        key={index}
+                        to={item.slug}
+                        style={{
+                            display: 'block',
+                            padding: '8px 16px',
+                            textDecoration: 'none',
+                            color: 'inherit'
+                        }}
+                        onClick={(e) => handleLinkClick(e, item.slug)}
+                    >
+                        {item.version}
+                    </Link>
+                ))}
+            </div>,
+            document.body
+        );
+
+    }
+
+        return(
+        <>
+            <div
+                className={styles.dropDownButton}
+                onClick={onClickHandler}
+                ref={buttonRef}
+            >
+                <div className={styles.versionText}>
+                    {props.versions[0]["version"]}
+                </div>
+                <span className={styles.triangle}></span>
+            </div>
+
+            {renderDropdown()}
+        </>
+    )
+}
+
+export default ClientVersionDropdown

src/theme/ClientVersionDropdown/styles.module.css

@@ -0,0 +1,73 @@
+/* Styling of the top level container */
+
+.dropDownButton {
+    display: flex;
+    margin-bottom: 24px;
+    align-items: center;
+    width: fit-content;
+    cursor: pointer;
+    border-style: solid;
+    border-width: 1px;
+    border-radius: 10px;
+    padding: 0px 15px 0px 10px;
+}
+
+.versionText{
+
+}
+
+/* Styling of the triangle in the dropdown button */
+
+.triangle {
+    position: relative;
+    display: inline-block;
+    margin-right: 5px;
+}
+
+.triangle::after {
+    content: "";
+    position: absolute;
+    top: 50%;
+    right: -15px; /* Adjust as needed */
+    width: 0;
+    height: 0;
+    border-left: 5px solid transparent;
+    border-right: 5px solid transparent;
+    transform: translateY(-50%);
+}
+
+[data-theme='dark'] .triangle::after {
+    border-top: 5px solid #ffff; /* Color of triangle */
+}
+
+[data-theme='light'] .triangle::after {
+    border-top: 5px solid #000; /* Color of triangle */
+}
+
+.dropdownItem {
+    display: block;
+    padding: 8px 16px;
+    text-decoration: none;
+    color: black;
+}
+
+.dropdownItem:hover {
+    background-color: #f5f5f5;
+}
+
+.dropdownStyleStatic {
+    position: absolute;
+    margin-top: 2px;
+    border-radius: 4px;
+    box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+    z-index: 1000;
+
+}
+
+[data-theme='dark'] .dropdownStyleStatic {
+    background-color: #3c3c3c;
+}
+
+[data-theme='light'] .dropdownStyleStatic {
+    background-color: white;
+}