vega · joelostblom · May 23, 2023 · May 18, 2023 · May 18, 2023 · May 18, 2023
diff --git a/doc/_static/altair-gallery.css b/doc/_static/altair-gallery.css
@@ -44,11 +44,13 @@ div.bottomnav {
 /* Front-page Example Showcase */
 #showcase {
   width: 100%;
-  height: 240px;
+  height: 300px;
   overflow: hidden;
   margin: 0;
   padding: 0;
-  position: relative;
+  position: absolute;
+  left: 0;
+  right: 0;
   margin-bottom: 10px;
 }
 #showcase:after,
@@ -71,13 +73,21 @@ div.bottomnav {
 }
 #showcase .examples {
   margin: 0 auto;
-  height: 240px;
-  width: 800px;
+  height: 300px;
   line-height: 0;
+  /* Width and padding settings give the example showcase the same width
+  as the page header on a big screen. On smaller screens, they both will
+  have the same width anyway as the title header is responsive and gets narrower
+  and the example showcase gets clipped by the overflow: hidden setting. */
+  width: 88rem;
+  padding-left: 1rem;
+  padding-right: 1rem;
 }
 #showcase .preview {
-  width: 144px;
-  height: 80px;
+  /* Value is chosen through trial and error so that the examples fill out the 
+  whole width which is defined in #showcase .examples */
+  width: 172px;
+  height: 100px;
   padding: 0;
   outline: 1px solid #ddd;
   background-position: left top;

diff --git a/doc/_static/custom.css b/doc/_static/custom.css
@@ -75,8 +75,21 @@ properly displayed on mobile devices and not restricted to 20% */
   width: 100%;
 }
 
-/* Use full page width without sidebars */
-/* .bd-content { */
-/*   max-width: 100%; */
-/*   flex-grow: 1; */
-/* } */
+/* Configurations for the start page
+------------------------------------ */
+.lead {
+  font-size: 1.3em;
+  font-weight: 300;
+  margin-top: 22px;
+  margin-bottom: 22px;
+  /* This pushes down the lead so that it is not rendered on top of
+  the gallery (showcase) which has an absolute position. The value is calculated
+  as height (showcase) + margin-bottom (showcase) + margin-top (lead) */
+  padding-top: 332px;
+}
+
+.lead strong {
+  /* Default is bolder which is less */
+  font-weight: bold;
+}
+/* ---------------------------------- */
diff --git a/doc/_static/theme_overrides.css b/doc/_static/theme_overrides.css
@@ -23,3 +23,8 @@
 img.logo {
     width: 120px !important;
 }
+
+/* Increas max-width of the content area slightly to accomodate larger screens */
+.bd-main .bd-content .bd-article-container {
+    max-width: 1000px;
+}
diff --git a/doc/case_studies/exploring-weather.rst b/doc/case_studies/exploring-weather.rst
@@ -263,7 +263,7 @@ This is the end of this tutorial where you have seen various ways to bin
 and aggregate data, derive new fields, and customize your charts.
 You can find more visualizations in the :ref:`example-gallery`.
 If you want to further customize your charts, you can refer to Altair's
-:ref:`API`.
+:ref:`api`.
 
 .. _Pandas: http://pandas.pydata.org/
 

diff --git a/doc/getting_started/overview.rst b/doc/getting_started/overview.rst
@@ -36,7 +36,7 @@ concise grammar.
 The project is named after the `brightest star <https://en.wikipedia.org/wiki/Altair>`_ 
 in the constellation Aquila. From Earth's sky Altair appears close to Vega, the star from which our parent project drew its name.
 
-This documentation serves as the main reference for learning about Altair. Additional learning material and tutorials can be found in the :ref:`learning-resources` section.
+This documentation serves as the main reference for learning about Altair. Additional learning material and tutorials can be found in the :ref:`learning-resources` section. It can also be helpful to browse the `Vega-Lite documentation <https://vega.github.io/vega-lite/docs/>`_.
 
 .. _Vega: http://vega.github.io/vega
 .. _Vega-Lite: http://vega.github.io/vega-lite

diff --git a/doc/index.rst b/doc/index.rst
@@ -5,16 +5,49 @@ Vega-Altair: Declarative Visualization in Python
 .. role:: raw-html(raw)
    :format: html
 
-
 .. altair-minigallery::
-   :names: one_dot_per_zipcode, horizon_graph, world_projections, candlestick_chart, falkensee, scatter_linked_brush, layered_heatmap_text, natural_disasters, streamgraph, multiline_tooltip, select_detail, choropleth, interactive_cross_highlight, seattle_weather_interactive, london_tube
-   :size: 15
+   :names: one_dot_per_zipcode, horizon_graph, world_projections, candlestick_chart, falkensee, errorbars_with_ci, scatter_linked_brush, line_with_ci, natural_disasters, bar_rounded, streamgraph, multiline_tooltip, choropleth, select_detail, interactive_cross_highlight, seattle_weather_interactive, london_tube, ridgeline_plot, violin_plot, strip_plot, table_bubble_plot_github, radial_chart, boxplot, mosaic_with_labels
+   :size: 24
+
+
+.. rst-class:: lead
+
+   **Vega-Altair** is a declarative visualization library for Python. Its simple, friendly and consistent API, built on top of the powerful Vega-Lite_ grammar, empowers you to spend less time writing code and more time exploring your data.
+
+
+.. grid:: 1 1 2 2
+   :padding: 0 2 3 5
+   :gutter: 2 2 3 3
+   :class-container: startpage-grid
+
+   .. grid-item-card:: Getting Started
+      :link: overview
+      :link-type: ref
+      :link-alt: Getting started
+
+      In the Getting Started section you can find installation instructions and a high-level overview of the main concepts.
+
+   .. grid-item-card:: User Guide
+      :link: user-guide-data
+      :link-type: ref
+      :link-alt: User guide
+
+      Check out the User Guides for in-depth information on the key concepts of Vega-Altair.
+
+   .. grid-item-card:: Examples
+      :link: example-gallery
+      :link-type: ref
+      :link-alt: Examples
+
+      The Examples gallery contains a selection of different visualizations which you can create with Vega-Altair.
 
-Vega-Altair is a declarative statistical visualization library for Python. 
+   .. grid-item-card:: API
+      :link: api
+      :link-type: ref
+      :link-alt: api
 
-Its simple, friendly and consistent API, built on top of the powerful Vega-Lite_ grammar, empowers you to spend less time writing code and more time exploring your data.
+      The API reference guide contains detailed information on all of Vega-Altair's methods and classes.
 
-You can browse this site via the links in the top navigation panel. It can also be helpful to browse the `Vega-Lite documentation <https://vega.github.io/vega-lite/docs/>`_.
 
 *The Vega-Altair open-source project is not affiliated with Altair Engineering, Inc.*
 
@@ -25,7 +58,7 @@ You can browse this site via the links in the top navigation panel. It can also
    Getting Started <getting_started/overview>
    User Guide <user_guide/data>
    Examples <gallery/index>
-   API <user_guide/API>
+   API <user_guide/api>
    user_guide/ecosystem
    releases/changes
 

diff --git a/doc/user_guide/API.rst → doc/user_guide/api.rst b/doc/user_guide/API.rst → doc/user_guide/api.rst
@@ -1,4 +1,4 @@
-.. _API:
+.. _api:
 
 API Reference
 =============

diff --git a/tools/generate_api_docs.py b/tools/generate_api_docs.py
@@ -1,20 +1,20 @@
 """
-This script fills the contents of doc/user_guide/API.rst
+This script fills the contents of doc/user_guide/api.rst
 based on the updated Altair schema.
 """
-from os.path import abspath, dirname, join
 import sys
 import types
+from os.path import abspath, dirname, join
 
 # Import Altair from head
 ROOT_DIR = abspath(join(dirname(__file__), ".."))
 sys.path.insert(0, ROOT_DIR)
 import altair as alt  # noqa: E402
 
-API_FILENAME = join(ROOT_DIR, "doc", "user_guide", "API.rst")
+API_FILENAME = join(ROOT_DIR, "doc", "user_guide", "api.rst")
 
 API_TEMPLATE = """\
-.. _API:
+.. _api:
 
 API Reference
 =============