Create sections for navigation menu

README.md

@@ -11,7 +11,67 @@ documentation and tutorials that are scoped to the features and
 capabilities of the library itself. The documentation for a library can be
 found under the `API Reference` section of [https://gazebosim.org/docs](https://gazebosim.org/docs).
 
-## Updating gazebosim.org
+## Documentation Structure
+
+The documentation is organized by Gazebo release version, with shared files located in a root-level `common` directory.
+
+### Repository Layout
+
+- **`common/`**: Contains markdown files and folders that are shared across all Gazebo releases (e.g., installation overviews, architecture guides, governance documents, etc.).
+- **`<release_name>/`** (e.g., `jetty/`): Contains markdown files specific to a particular release and its specific `index.yaml`.
+
+### Release Navigation Menu (`index.yaml`)
+
+Navigation menus are defined per-release in the release directory's `index.yaml` (e.g., `jetty/index.yaml`). The top-level `index.yaml` only contains global release metadata and library information, not navigation definitions.
+
+#### Organizing Pages with Sections
+
+The `pages` key in the release `index.yaml` defines the menu hierarchy using the `section` key to group related items.
+
+Example:
+
+```yaml
+pages:
+  - section: Get Started
+    children:
+      - name: getstarted
+        title: Get Started
+        file: common:get_started.md
+      - name: release_notes
+        title: Release Notes
+        file: release_notes.md
+```
+
+#### Shared Files Prefix (`common:`)
+
+To reference a file from the root-level `common` directory in a release-specific `index.yaml`, use the `common:` prefix in the `file` attribute.
+
+```yaml
+- name: getstarted
+  title: Get Started
+  file: common:get_started.md
+```
+
+Files without the prefix are assumed to be relative to the release directory.
+
+#### Reusing Common Navigation Items (`!include`)
+
+To avoid duplication across versioned `index.yaml` files, you can use the `!include` tag to include shared lists of navigation items from the `common/` directory.
+
+Example:
+```yaml
+- section: Reference
+  children:
+    - !include common/nav_reference.yaml
+    - name: release_notes
+      title: Release Notes
+      file: release_notes.md
+```
+The build script will resolve the `!include` tag and flatten the list, effectively merging the shared items with any release-specific items listed before or after it.
+
+#### Organizational Elements
+
+If an entry in `index.yaml` has children but no `file` entry, it is considered an organizational element. The build script will automatically create a placeholder page for Sphinx to group the children under.
 
 ## Main docs
 

acropolis/index.yaml

@@ -1,29 +1,59 @@
 # This file is an index of the pages to display on the documentation website
-# (https://gazebosim.org/docs). The order of the pages in this file
+# for this specific release. The order of the pages in this file
 # is reflected on the website's left sidebar.
 #
-# Components of the index:
-#
-# 1. "pages:" The master list of pages
+# For more information about the structure of this file, see the README.md file at the root of the repository.
 #
-# 2. Each page has a
-#    a. "name:" This should be a short url-friendly and unique name. It will
-#    be used in the website url.
+# Components of the index:
 #
-#    b. "title:" This is a human-friendly title for the page. This title will
-#    be displayed on the website's left side bar.
+# "pages:" A list of top-level items, which should be "section"s.
+# Each section has a "section" title and a list of "children" (pages).
 #
-#    c. "file:" The markdown file that contains the page's content.
+# Each page has:
+# - "name:" A short url-friendly and unique name used in the website url.
+# - "title:" A human-friendly title displayed on the website's left sidebar.
+# - "file:" The markdown file that contains the page's content.
+#   Prefix with "common:" if the file is in the top-level "common/" directory.
+# - "description:" (Optional) A short description for the page.
+# - "children:" (Optional) A list of sub-pages.
 pages:
-  - name: install
-    title: Install
-    file: install.md
-    description: Citadel installation instructions
-  - name: ros_integration
-    title: ROS Integration
-    file: ros_integration.md
-    description: This tutorial details how to interface with ROS, enabling the ability to use tools such as Rviz for robot or sensor visualization.
-  - name: comparison
-    title: Feature Comparison
-    file: comparison.md
-    description: A list of features present in Gazebo-classic and the status of their migration to Gazebo.
+  - section: Get Started
+    children:
+      - name: getstarted
+        title: Get Started
+        file: common:get_started.md
+        description: Getting started with Gazebo.
+      - name: install
+        title: Install
+        file: install.md
+        description: Citadel installation instructions
+      - name: ros_installation
+        title: ROS/Gazebo Installation
+        file: common:ros_installation.md
+        description: Ros and Gazebo options and combinations
+        children:
+          - name: ros2_gz_vendor_pkgs
+            title: ROS 2 Gazebo Vendor Packages
+            file: common:ros2_gz_vendor_pkgs.md
+            description: Using ROS 2 Gazebo Vendor packages
+  - section: For Users
+    children:
+      - name: how_to_guides
+        title: How-to Guides
+        children:
+          - name: ros_integration
+            title: ROS Integration
+            file: ros_integration.md
+            description: This tutorial details how to interface with ROS, enabling
+              the ability to use tools such as Rviz for robot or sensor visualization.
+  - section: For Developers
+    children:
+      - !include common/nav_for_developers.yaml
+
+  - section: Reference
+    children:
+      - !include common/nav_reference.yaml
+
+  - section: Migration Guides
+    children:
+      - !include common/nav_migration_guides.yaml

acropolis/library_howtos.md

@@ -0,0 +1,11 @@
+# Gazebo Library How-To Guides
+
+See the *API & Tutorials* sections on the [Libraries page](/libs){.external} page for more specific content correlating to each Gazebo library.
+
+The entrypoint library is Sim.
+
+{{ gz_sim_link }}
+
+Other libraries:
+
+{{ libraries_list }}

blueprint/index.yaml

@@ -1,45 +1,81 @@
 # This file is an index of the pages to display on the documentation website
-# (https://ignitionrobotics.org/docs). The order of the pages in this file
+# for this specific release. The order of the pages in this file
 # is reflected on the website's left sidebar.
 #
-# Components of the index:
-#
-# 1. "pages:" The master list of pages
+# For more information about the structure of this file, see the README.md file at the root of the repository.
 #
-# 2. Each page has a
-#    a. "name:" This should be a short url-friendly and unique name. It will
-#    be used in the website url.
+# Components of the index:
 #
-#    b. "title:" This is a human-friendly title for the page. This title will
-#    be displayed on the website's left side bar.
+# "pages:" A list of top-level items, which should be "section"s.
+# Each section has a "section" title and a list of "children" (pages).
 #
-#    c. "file:" The markdown file that contains the page's content.
+# Each page has:
+# - "name:" A short url-friendly and unique name used in the website url.
+# - "title:" A human-friendly title displayed on the website's left sidebar.
+# - "file:" The markdown file that contains the page's content.
+#   Prefix with "common:" if the file is in the top-level "common/" directory.
+# - "description:" (Optional) A short description for the page.
+# - "children:" (Optional) A list of sub-pages.
 pages:
-  - name: install
-    title: Install
-    file: install.md
-    description: Blueprint installation instructions
-  - name: ros_integration
-    title: ROS Integration
-    file: ros_integration.md
-    description: This tutorial details how to interface with ROS, enabling the ability to use tools such as Rviz for robot or sensor visualization.
-  - name: comparison
-    title: Feature Comparison
-    file: comparison.md
-    description: A list of features present in Gazebo-classic and the status of their migration to Ignition.
-  - name: gui
-    title: Understanding the GUI
-    file: GUI_tutorial.md
-    description: This guide is an introduction to the Ignition Graphical User Interface (GUI).
-  - name: manipulating_models
-    title: Manipulating Models
-    file: Manipulating_models.md
-    description: This tutorial will walk you through using various plugins to assist model and scene manipulation in the Ignition GUI.
-  - name: fuel_insert
-    title: Model Insertion from Fuel
-    file: Model_insertion_fuel.md
-    description: Ignition Fuel hosts hundreds of models that can easily be added to a world running in the Ignition GUI.
-  - name: hotkeys
-    title: Keyboard Shortcuts
-    file: hotkeys.md
-    description: Ignition keyboard shortcuts
+  - section: Get Started
+    children:
+      - name: getstarted
+        title: Get Started
+        file: common:get_started.md
+        description: Getting started with Gazebo.
+      - name: install
+        title: Install
+        file: install.md
+        description: Blueprint installation instructions
+      - name: ros_installation
+        title: ROS/Gazebo Installation
+        file: common:ros_installation.md
+        description: Ros and Gazebo options and combinations
+        children:
+          - name: ros2_gz_vendor_pkgs
+            title: ROS 2 Gazebo Vendor Packages
+            file: common:ros2_gz_vendor_pkgs.md
+            description: Using ROS 2 Gazebo Vendor packages
+  - section: For Users
+    children:
+      - name: tutorials
+        title: Simulation Tutorials
+        children:
+          - name: gui
+            title: Understanding the GUI
+            file: GUI_tutorial.md
+            description: This guide is an introduction to the Ignition Graphical User
+              Interface (GUI).
+          - name: manipulating_models
+            title: Manipulating Models
+            file: Manipulating_models.md
+            description: This tutorial will walk you through using various plugins
+              to assist model and scene manipulation in the Ignition GUI.
+          - name: fuel_insert
+            title: Model Insertion from Fuel
+            file: Model_insertion_fuel.md
+            description: Ignition Fuel hosts hundreds of models that can easily be
+              added to a world running in the Ignition GUI.
+          - name: hotkeys
+            title: Keyboard Shortcuts
+            file: hotkeys.md
+            description: Ignition keyboard shortcuts
+      - name: how_to_guides
+        title: How-to Guides
+        children:
+          - name: ros_integration
+            title: ROS Integration
+            file: ros_integration.md
+            description: This tutorial details how to interface with ROS, enabling
+              the ability to use tools such as Rviz for robot or sensor visualization.
+  - section: For Developers
+    children:
+      - !include common/nav_for_developers.yaml
+
+  - section: Reference
+    children:
+      - !include common/nav_reference.yaml
+
+  - section: Migration Guides
+    children:
+      - !include common/nav_migration_guides.yaml

blueprint/library_howtos.md

@@ -0,0 +1,11 @@
+# Gazebo Library How-To Guides
+
+See the *API & Tutorials* sections on the [Libraries page](/libs){.external} page for more specific content correlating to each Gazebo library.
+
+The entrypoint library is Sim.
+
+{{ gz_sim_link }}
+
+Other libraries:
+
+{{ libraries_list }}