Opengraph improvements

CHANGELOG.md

@@ -9,6 +9,7 @@
 * [Doc] Add chDB integration tutorial
 * [Doc] Clarify the use of `pyproject.toml` and `connections.ini` in documentations (#850)
 * [Fix] Fix result not displayed when `SUMMARIZE` argument is used in duckdb with a sqlalchemy connection (#836)
+* [Doc] Opengraph/Sphinxext-opengraph Integration and Optimization for Social Media link Sharing (#253)
 
 ## 0.10.1 (2023-08-30)
 

doc/community/developer-guide.md

@@ -568,3 +568,116 @@ As you can see, output results are different
 From duckdb dialect: `'SELECT TO_TIMESTAMP(1618088028295)'`
 
 From sqlite dialect: `'SELECT UNIX_TO_TIME(1618088028295)'`
+
+## Enhancing Social Media/SEO Previews: Integrating Open Graph Tags
+
+Open Graph tags hold metadata (such as images and descriptions) that influence how links are presented on social media platforms and in search engine results. [Sphinxext-opengraph](https://sphinxext-opengraph.readthedocs.io/en/latest/) extension package enables us to add/modify Open Graph Tags.
+
+### Tab titles
+
+To change the tab title of the entire website modify the html_title tag in the conf file in the doc folder. Here are a few cases:
+
+    html_title = "JupySQL documentation" # case 1: Sets to "JupySQL documentation" as title
+    html_title = "" # case 2: Empty title
+				    #case 3: no html_title tag will result in default "Python documentation" title by Sphinx
+
+### Page titles
+
+#### Individual pages
+
+To change the title of individual page add the og:title tag on top of targeted markdown file
+
+```
+---
+og:image: /en/685/_static/duckdb.png
+og:image:alt: 'Better SQL in Jupyter. 📊.'
+og:description: 'Duckdb'
+og:title: 'Duckdb title' # Title tag
+jupytext:
+  notebook_metadata_filter: myst
+  text_representation:
+	extension: .md
+	format_name: myst
+	format_version: 0.13
+	jupytext_version: 1.14.7
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+myst:
+  html_meta:
+	description lang=en: Use DuckDB from Jupyter using JupySQL
+	keywords: jupyter, sql, jupysql, duckdb, plotting
+	property=og:locale: en_US
+---
+
+# DuckDB # default title
+```
+By default, the title of the individual page will be the first header on the markdown page. In our case, it's 'DuckDB'. Here are some other cases:
+
+    # case 1: No og:title tag, the page title will be "DuckDB"
+
+    og:title: '' # case 2: Page title will be empty
+
+    og:title: 5 # case 3: Page title will be "5"
+
+    og:title: # case 4: Page title will be "null"
+
+### Page Image
+
+#### Entire website
+
+Open Graph image tags control how links are previewed on social media sites. By default, the image is set to null. To add an Open Graph image, add/modify the ogp_image and ogp_image_alt tags in the conf file inside the doc folder. These images will than become default image for all pages.
+
+    ogp_image: "/en/685/_static/html-meta-template.png" # takes a URL link to the image, case 1: If images are hosted in the repo*
+
+    ogp_image: "url goes here" # case 2: Any other image on the web
+
+    ogp_image_alt:"Better SQL in Jupyter. 📊."
+
+*The Sphinxext-opengraph extension creates an og:image link by combining ogp_site_url and ogp_image. The ogp_site_url tag takes the site url as default, in our case url: "https://jupysql.ploomber.io", thus the final image link will be: https://jupysql.ploomber.io + /en/685/_static/html-meta-template.png, ogp_site_url can be given a different value by adding the tag in the conf file.
+
+    ogp_site_url = "https://jupysql.ploomber.io"
+
+#### Individual page
+
+The Sphinxext-opengraph package provides us with tags to enable Open Graph tags on individual pages. To add an Open Graph Image, include the og:image tag at the top of the individual markdown file. This will ensure that the image is considered and will override the default og:image for that particular page.
+
+```
+---
+og:image: /en/685/_static/duckdb.png  # Open Graph image for this page
+og:image:alt: 'Better SQL in Jupyter. 📊.'
+og:description: 'Duckdb'
+og:title: 'Duckdb title' # Title tag
+jupytext:
+  notebook_metadata_filter: myst
+  text_representation:
+	extension: .md
+	format_name: myst
+	format_version: 0.13
+	jupytext_version: 1.14.7
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+myst:
+  html_meta:
+	description lang=en: Use DuckDB from Jupyter using JupySQL
+	keywords: jupyter, sql, jupysql, duckdb, plotting
+	property=og:locale: en_US
+---
+
+# DuckDB # default title
+```
+
+##### Hosting images in the repo
+
+In many cases, we won't be using external links as og:image; instead, we would use images from our repo. In this case, we will store all the static images in the "_static" folder under the doc folder. This will allow us to access them after the build at the "~/build/_static/" path.
+
+Things to keep in mind:
+
+- Image file should be under 8 MB
+
+- The recommended size for og:image is 1,200 x 630 pixels. Use "https://www.drawio.com/" to create the image and store it in the "_static" folder. Also, save the drawio file in the "assets" folder under the doc folder.
+
+- Double-check the image after it is hosted in your browser to ensure that it is accessible.

doc/conf.py

@@ -47,6 +47,7 @@
     "sphinx.ext.autosummary",
     "matplotlib.sphinxext.plot_directive",
     "sphinx_jupyterbook_latex",
+    "sphinxext.opengraph",
 ]
 external_toc_exclude_missing = False
 external_toc_path = "_toc.yml"
@@ -55,6 +56,7 @@
 html_logo = "square-no-bg-small.png"
 html_sourcelink_suffix = ""
 html_theme = "sphinx_book_theme"
+html_title = "JupySQL documentation"
 html_theme_options = {
     "launch_buttons": {
         "notebook_interface": "jupyterlab",
@@ -99,6 +101,8 @@
 suppress_warnings = ["misc.highlighting_failure"]
 use_jupyterbook_latex = True
 use_multitoc_numbering = True
+ogp_image = "/en/685/_static/html-meta-template.png"
+ogp_image_alt = "Better SQL in Jupyter. 📊."
 
 
 # Adding Algolia search to jupyter-book :

doc/environment.lock.yml

@@ -201,4 +201,5 @@ dependencies:
       - wcwidth==0.2.6
       - widgetsnbextension==4.0.8
       - zipp==3.16.2
+      - sphinxext-opengraph
 prefix: /opt/conda/envs/jupysql-doc

doc/integrations/chdb.md

@@ -31,6 +31,7 @@ JupySQL integrates with chDB so you can run SQL queries in a Jupyter notebook. J
 
 ```{code-cell} ipython3
 from chdb import dbapi
+
 conn = dbapi.connect()
 
 %load_ext sql
@@ -39,10 +40,9 @@ conn = dbapi.connect()
 
 ### Get a sample `.parquet` file:
 
-+++
-
 ```{code-cell} ipython3
 from urllib.request import urlretrieve
+
 _ = urlretrieve(
     "https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2021-01.parquet",
     "yellow_tripdata_2021-01.parquet",
@@ -53,7 +53,6 @@ _ = urlretrieve(
 
 +++
 
-
 Query a local file
 
 ```{code-cell} ipython3
@@ -65,6 +64,7 @@ GROUP BY passenger_count
 ```
 
 Run a file over HTTP
+
 ```{code-cell} ipython3
 %%sql
 SELECT
@@ -77,4 +77,3 @@ GROUP BY
 ORDER BY c
 DESC LIMIT 10
 ```
-

doc/integrations/duckdb.md

@@ -1,4 +1,6 @@
 ---
+og:image: /en/685/_static/duckdb.png
+og:image:alt: 'Better SQL in Jupyter. 📊.'
 jupytext:
   notebook_metadata_filter: myst
   text_representation:

doc/user-guide/table_explorer.ipynb

@@ -30,11 +30,7 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "67e9f89e",
-   "metadata": {
-    "vscode": {
-     "languageId": "python"
-    }
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "from pathlib import Path\n",
@@ -59,11 +55,7 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "2708d4a7",
-   "metadata": {
-    "vscode": {
-     "languageId": "python"
-    }
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "%pip install jupysql jupysql-plugin --upgrade --quiet"
@@ -86,11 +78,7 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "dbe40317",
-   "metadata": {
-    "vscode": {
-     "languageId": "python"
-    }
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "%load_ext sql\n",
@@ -112,11 +100,7 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "7e6c6c7d",
-   "metadata": {
-    "vscode": {
-     "languageId": "python"
-    }
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "%sqlcmd explore --table \"yellow_tripdata_2021.parquet\""
@@ -137,16 +121,25 @@
    "notebook_metadata_filter": "myst"
   },
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "ploomber_env",
    "language": "python",
    "name": "python3"
   },
+  "language_info": {
+   "name": "python",
+   "version": "3.9.6 (default, Oct 18 2022, 12:41:40) \n[Clang 14.0.0 (clang-1400.0.29.202)]"
+  },
   "myst": {
    "html_meta": {
     "description lang=en": "Templatize SQL queries in Jupyter via JupySQL",
     "keywords": "jupyter, sql, jupysql, jinja",
     "property=og:locale": "en_US"
    }
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "70d770717fb5a42e0e8fc57cee0e68de4e4328ed30e100d18878b58ca475a80f"
+   }
   }
  },
  "nbformat": 4,