From ade7e5a33749a341d063606ccbf6add0ec219727 Mon Sep 17 00:00:00 2001 From: Aayushman-nvm Date: Wed, 25 Feb 2026 12:30:21 +0000 Subject: [PATCH] fix: Automate tutorial sidebar generation --- _data/tutorial_sidebar_config.yml | 103 +++++++++++++++ _includes/sidebar.html | 181 +++++++++++++++---------- _includes/tutorial_sidebar.html | 213 ++++++++++++++++++++++++++++++ 3 files changed, 429 insertions(+), 68 deletions(-) create mode 100644 _data/tutorial_sidebar_config.yml create mode 100644 _includes/tutorial_sidebar.html diff --git a/_data/tutorial_sidebar_config.yml b/_data/tutorial_sidebar_config.yml new file mode 100644 index 00000000000..092aaf6141f --- /dev/null +++ b/_data/tutorial_sidebar_config.yml @@ -0,0 +1,103 @@ +# _data/tutorial_sidebar_config.yml +# =================================== +# Single source of truth for tutorial sidebar navigation decisions. +# Lives in the MAIN SITE REPO (_data/), never in the tutorials submodule. +# +# HUGO MIGRATION: +# Read via $.Site.Data.tutorial_sidebar_config — identical structure. +# Only the template syntax changes, not this file. +# +# TITLE OVERRIDES: +# Both `featured` entries and group `permalinks` support an optional `title` +# field. If present it overrides the verbose README title with a short display +# name matching the original tutorial_sidebar.yml. If absent, the template +# falls back to the page's own `title` front matter. +# +# ADDING A NEW TUTORIAL: +# - Appears in "All tutorials" automatically with no changes here. +# - To feature it in Basic cases: add an entry under `featured`. +# - To put it in a named group: add an entry under the group's `permalinks`. +# - To create a new group: add a new block under `groups`. + +# ------------------------------------------------------------------------------ +# Basic cases +# Rendered in ascending `order`. Title overrides the README title if present. +# ------------------------------------------------------------------------------ +featured: + - permalink: quickstart.html + order: 1 + title: Quickstart + - permalink: tutorials-flow-over-heated-plate.html + order: 2 + title: Flow over a heated plate + - permalink: tutorials-partitioned-heat-conduction.html + order: 3 + title: Partitioned heat conduction + - permalink: tutorials-perpendicular-flap.html + order: 4 + title: Perpendicular flap + +# ------------------------------------------------------------------------------ +# Subgroups +# Each group becomes a collapsible sub-folder in "All tutorials". +# Groups and flat pages are interleaved alphabetically by display name — +# the `name` field is used as the sort key alongside flat page titles. +# `order` is NOT used for positioning within All tutorials (alphabetical +# interleaving handles that). `order` is kept for potential future use +# and documents editorial intent. +# Pages within each group are sorted alphabetically by their display title. +# ------------------------------------------------------------------------------ +groups: + - name: Channel transport + order: 1 + permalinks: + - url: tutorials-channel-transport.html + title: Basic variant + - url: tutorials-channel-transport-reaction.html + title: Reaction + - url: tutorials-channel-transport-particles.html + title: Particles + + - name: Flow over a heated plate + order: 2 + permalinks: + - url: tutorials-flow-over-heated-plate.html + title: Basic variant + - url: tutorials-flow-over-heated-plate-nearest-projection.html + title: Nearest-projection mapping + - url: tutorials-flow-over-heated-plate-steady-state.html + title: Steady state + - url: tutorials-flow-over-heated-plate-two-meshes.html + title: Two meshes + + - name: Partitioned flow + order: 3 + permalinks: + - url: tutorials-partitioned-backwards-facing-step.html + title: Partitioned flow over a b.f. step + - url: tutorials-flow-over-heated-plate-partitioned-flow.html + title: Partitioned flow over heated plate + - url: tutorials-partitioned-pipe.html + title: Partitioned pipe + - url: tutorials-partitioned-pipe-two-phase.html + title: Partitioned pipe two-phase + + - name: Partitioned heat conduction + order: 4 + permalinks: + - url: tutorials-partitioned-heat-conduction.html + title: Basic variant + - url: tutorials-partitioned-heat-conduction-complex.html + title: Complex variant + - url: tutorials-partitioned-heat-conduction-direct.html + title: Direct mesh access + - url: tutorials-partitioned-heat-conduction-overlap.html + title: Overlapping Schwarz + + - name: Perpendicular flap + order: 5 + permalinks: + - url: tutorials-perpendicular-flap.html + title: Basic variant + - url: tutorials-perpendicular-flap-stress.html + title: Stress variant \ No newline at end of file diff --git a/_includes/sidebar.html b/_includes/sidebar.html index 73645c9a5b9..37626d1d25f 100644 --- a/_includes/sidebar.html +++ b/_includes/sidebar.html @@ -1,74 +1,119 @@ -{% assign sidebar = site.data.sidebars[page.sidebar].entries %} +{% if page.sidebar == 'tutorial_sidebar' %} + {% include tutorial_sidebar.html %} +{% else %} + {% assign sidebar = site.data.sidebars[page.sidebar].entries %} - + - - + +{% endif %} diff --git a/_includes/tutorial_sidebar.html b/_includes/tutorial_sidebar.html new file mode 100644 index 00000000000..0f6461cf696 --- /dev/null +++ b/_includes/tutorial_sidebar.html @@ -0,0 +1,213 @@ +{% comment %} + tutorial_sidebar.html + ===================== + Renders the tutorials sidebar automatically from site.pages at build time. + All navigation decisions live in _data/tutorial_sidebar_config.yml for + exclusive links like "Basic cases" or named groups in "All tutorials". + Tutorial READMEs need no special front matter beyond `title` and `permalink`. + + STRUCTURE: + 1. Introduction — hardcoded (not in submodule) + 2. Basic cases — from tutorial_sidebar_config.yml `featured` list + 3. All tutorials — auto-discovered flat pages + named groups, interleaved + alphabetically by display name +{% endcomment %} + +{% comment %} + ============================================================ + STEP 1 — Collect tutorial pages into parallel lookup arrays + ============================================================ +{% endcomment %} +{% assign tutorial_pages = '' | split: '' %} +{% assign tutorial_permalinks = '' | split: '' %} +{% for p in site.pages %} + {% if p.path contains 'imported/tutorials/' %} + {% assign tutorial_pages = tutorial_pages | push: p %} + {% assign tutorial_permalinks = tutorial_permalinks | push: p.permalink %} + {% endif %} +{% endfor %} + +{% comment %} + ============================================================ + STEP 2 — Build lookup sets from the data file + ============================================================ + featured_urls: used to suppress active class in Basic cases only. + Featured pages ARE rendered in All tutorials with normal + active class — that is their canonical active location. + grouped_urls: used to exclude pages from the flat list in All tutorials + (they appear inside their named group instead). +{% endcomment %} +{% assign featured_urls = '' | split: '' %} +{% for f in site.data.tutorial_sidebar_config.featured %} + {% assign featured_urls = featured_urls | push: f.permalink %} +{% endfor %} + +{% assign grouped_urls = '' | split: '' %} +{% for group in site.data.tutorial_sidebar_config.groups %} + {% for gentry in group.permalinks %} + {% assign grouped_urls = grouped_urls | push: gentry.url %} + {% endfor %} +{% endfor %} + +{% comment %} + ============================================================ + STEP 3 — Build the unified All tutorials entry list + ============================================================ + Flat pages: all tutorial pages NOT in any group. + Featured pages ARE included here as flat entries if they + are not also in a group (e.g. Quickstart). + Featured pages that ARE in a group (e.g. Flow over a heated + plate) will appear inside their group, not as flat entries. + Group entries: one per group, sorted by group name alongside flat pages. +{% endcomment %} +{% assign all_entries = '' | split: '' %} + +{% for p in tutorial_pages %} + {% unless grouped_urls contains p.permalink %} + {% assign raw_idx = forloop.index0 %} + {% assign padded_idx = raw_idx | prepend: '000' | slice: -4, 4 %} + {% assign entry = p.title | append: '^flat^' | append: padded_idx %} + {% assign all_entries = all_entries | push: entry %} + {% endunless %} +{% endfor %} + +{% for group in site.data.tutorial_sidebar_config.groups %} + {% assign entry = group.name | append: '^group^' | append: group.name %} + {% assign all_entries = all_entries | push: entry %} +{% endfor %} + +{% assign all_entries = all_entries | sort %} + +{% comment %} + ============================================================ + STEP 4 — Sort featured list by order field + ============================================================ +{% endcomment %} +{% assign sorted_featured = site.data.tutorial_sidebar_config.featured | sort: 'order' %} + +{% comment %} + ============================================================ + RENDER + ============================================================ +{% endcomment %} + + +