Docs: CI improvements

apps/docs/DEPLOYMENT.md

@@ -1,10 +1,7 @@
 # Deploying the Documentation Site
 
 ## Environment Variables
-- `PROJECT_ROOT`: The root directory of the project.
-- `BUILD_REPO`: The Git repository URL for the documentation site.
-- `PRODUCT_VERSION`: The version of the product being documented.
-- `BUILD_LATEST`: A boolean flag indicating whether to build the `latest` version.
+See [`scripts/README.md`](./scripts/README.md) for the environment variables `deploy.sh` reads (including `DEPLOY_MODE` for staging).
 
 ## Overview
 
@@ -13,18 +10,18 @@ set -e
 source .env
 ```
 
-First, we need to build the documentation site via `$PROJECT_ROOT/generate.sh`. This creates static files in the
-`$PROJECT_ROOT/apps/.build` directory.
+First, we need to build the documentation site via `$PROJECT_ROOT/scripts/generate.sh`. This creates static files in the
+`$PROJECT_ROOT/.build` directory.
 
 ```
 $PROJECT_ROOT
 ├── 📂 .build
-│   ├── 📁 <product_version>          <!-- Version with non-prefixed URL -->
-│   ├── 📁 <product_version>          <!-- Version with prefixed URL -->
+│   ├── 📁 latest                     <!-- Build with non-prefixed URL -->
+│   ├── 📁 <product_version>          <!-- Build with prefixed URL -->
 ```
 
 ```sh
-yarn run build-docs
+yarn run docs:build
 ```
 
 Second, we read the current contents of the `$BUILD_REPO/main` branch, this includes a `versions.json` file that lists
@@ -50,10 +47,10 @@ Third, we update the `versions.json` file with the new version information, incl
 
 ```bash
 # cwd: $PROJECT_ROOT/.repo
-node ../.github/update-versions.js
+node ../scripts/update-versions.cjs
 ```
 
-Fourth, we copy the newly built static files from `$PROJECT_ROOT/apps/.build` into the appropriate directories in the
+Fourth, we copy the newly built static files from `$PROJECT_ROOT/.build` into the appropriate directories in the
 documentation repository. If the directory exists, we overwrite its contents. If it does not exist, we create it. We
 only copy `latest` if the environment flag `BUILD_LATEST` is set to `true`.
 

apps/docs/README.md

@@ -10,11 +10,14 @@ Most scripts are prefixed. Scripts `docs:*` are scripts intended for CI/CD while
 Typically, you want to run this project in dev mode via `yarn run nuxt:dev:no-autogen`. This disables the template handler from running on Autogen on every route change. You can run `yarn run nuxt:prepare` to generate the `content` directory from `autogen` before running in dev mode.
 
 ### Known Issues
-> :warning: Running `nuxt:prepare` while the dev server is running will break the dev server until it is restarted. This is expected behavior as `nuxt:prepare` modifies the `.nuxt` directory.
+> [!WARNING]
+> Running `nuxt:prepare` while the dev server is running will break the dev server until it is restarted. This is expected behavior as `nuxt:prepare` modifies the `.nuxt` directory.
 
-> :warning: The handler is light and can run efficiently on route transition but it results in issues with `@nuxt/content` when run with many files.
+> [!WARNING]
+> The handler is light and can run efficiently on route transition but it results in issues with `@nuxt/content` when run with many files.
 
-> :warning: If you are getting weird issues with the dev server, try stopping it, remove the `.nuxt` directory, and re-run via `yarn run nuxt:prepare` followed by `yarn run nuxt:dev:no-autogen`.
+> [!WARNING]
+>  If you are getting weird issues with the dev server, try stopping it, remove the `.nuxt` directory, and re-run via `yarn run nuxt:prepare` followed by `yarn run nuxt:dev:no-autogen`.
 
 ### Bypassing Confirmation Prompts
 Some scripts require confirmation before proceeding. You can bypass these prompts by using the handy [`yes`](https://en.wikipedia.org/wiki/Yes_(Unix)) command. For example:
@@ -24,54 +27,35 @@ yes | yarn run docs:deploy
 ```
 
 ### Overview of `docs:*` scripts
+For the environment variables and options each script accepts, see [`scripts/README.md`](./scripts/README.md).
+
 #### `docs:build`
-Builds the site via `nuxt:build`. It will create a `.build` folder containing the following:
+Builds the site via `nuxt:generate` (through `scripts/generate.sh`). It will create a `.build` folder containing the following:
 
 ```
 📂 (root)
 ├── 📂 .build
-│   ├── 📁 <product_version>          <!-- Version with non-prefixed URL -->
-│   ├── 📁 <product_version>          <!-- Version with prefixed URL -->
+│   ├── 📁 latest                     <!-- Build with non-prefixed URL (BASE_PATH='/') -->
+│   ├── 📁 <product_version>          <!-- Build with prefixed URL (BASE_PATH='/<product_version>/') -->
 └── ...
 ```
 
-The 📁 `latest` directory contains a build with `BASE_PATH='/'` while `<product_version>` contains a build with `BASE_PATH='<product_version>`.
+The 📁 `latest` directory contains a build with `BASE_PATH='/'` while `<product_version>` contains a build with `BASE_PATH='<product_version>`. `latest` is only built when `BUILD_LATEST=true`.
 
 ##### Logging
 The output of `stdout` and `stderr` from the build process is captured in `.stdout.log` and `.stderr.log` respectively in the project root.
 
-##### Known Issues
-This script is known to get stuck sometimes due to Nuxt's build process, particularly, when run in the VSCode terminal on macOS. If this happens, try running the command in a different terminal (e.g., iTerm2, Terminal.app) or simply re-running the command. You will know the build is stuck if you find this message in `.stdout.log` at the end of the file with no further output after it for more than a few seconds:
-
-```
-[nuxi] ✔ You can now deploy .output/public to any static hosting!
-```
 
 Keep in mind this script may take several minutes to complete.
 
-##### Options
-- (via environment) `BUILD_LATEST`: builds the `.build/latest` directory.
-- (via environment) `PRODUCT_VERSION`: sets the product version for the build.
-
 #### `docs:generate-manual`
 Generates the NetLogo User Manual from a build. The `.build/latest` directory must exist prior to running this command or it will ask you to run `docs:build` first. The generated PDF will be placed at the top level of `.build/latest` and `.build/<product_version>`.
 
-##### Options
-- (via environment) `PRODUCT_VERSION`: sets the product version for the build, visible in the title page of the generated PDF.
-- (via environment) `PORT`: sets the port for the preview server. Default: `3002`.
-
 #### `docs:deploy`
 Documented in detail in [deploying the documentation site](./DEPLOYMENT.md). In short, it handles the commit to the github repository.
 
-##### Options
-- (via environment) `PROJECT_ROOT`: sets the project root for the build (usually: `.`).
-- (via environment) `PRODUCT_DISPLAY_NAME`: sets the product display name for the build.
-- (via environment) `PRODUCT_VERSION`: sets the product version for the build.
-- (via environment) `BUILD_REPO`: sets the repository to push the built documentation to.
-- (via environment) `BUILD_BRANCH`: sets the branch to push the built documentation to.
-
 #### `docs:all`
-Runs `docs:build`, `docs:generate-manual`, and `docs:deploy` in sequence.
+Runs `docs:clean-up`, `docs:build`, `docs:generate-manual`, and `docs:deploy` in sequence.
 
 ##### Benchmark
 On M1 MacBook Air (2020):
@@ -82,8 +66,8 @@ On M1 MacBook Air (2020):
 #### `docs:preview`
 Previews the documentation site locally. If `latest` exists, it unrolls it in a `.preview` directory for previewing. Otherwise, it uses the `PRODUCT_VERSION` directory.
 
-#### `docs:make-static-site`
-Creates a static export of the documentation site in `.build-static`. Static here refers to a site that can be loaded via the `file://` protocol. It uses relative paths and inlining for all assets. This exports only a subset of directories: the home page and top-level manual pages. It does not support javascript.
+#### `docs:build:offline`
+Creates an offline build of the site in `.build/latest`, loadable via the `file://` protocol. It runs `nuxt:generate` with `DOCS_ENV_STATIC=1`, then generates the PDF manual.
 
 #### `docs:clean-up`
 Cleans up all build and preview artifacts.

apps/docs/app/app.vue

@@ -6,3 +6,13 @@
     </NuxtErrorBoundary>
   </NuxtLayout>
 </template>
+
+<script setup lang="ts">
+const { public: { isOffline } } = useRuntimeConfig();
+
+useHead({
+  htmlAttrs: {
+    'data-mode': isOffline ? 'offline' : 'online',
+  },
+});
+</script>

apps/docs/app/components/ClientFooter.vue

@@ -47,7 +47,7 @@
 </template>
 
 <script setup lang="ts">
-import NetLogoUserManualLogo from '@repo/vue-ui/assets/brands/NetLogoUserManual.svg';
+import NetLogoUserManualLogo from '@repo/vue-ui/assets/brands/NetLogoUserManual.svg?url';
 import type { FooterLink } from '@repo/vue-ui/components/footer/types';
 import { onMounted, ref } from 'vue';
 

apps/docs/app/components/ClientNavbar.vue

@@ -23,9 +23,10 @@
     </NavbarLinksContainer>
 
     <NavbarActionsContainer>
-      <SSRUContentSearchButton />
+      <SSRUContentSearchButton v-if="!isOffline" />
 
       <VersionSelectDropdown
+        v-if="!isOffline"
         :versions="versions"
         :selected-version="selectedVersion"
         @version-change="(version) => onVersionChange(version, { productVersion, productWebsite })"
@@ -49,8 +50,8 @@
 </template>
 
 <script setup lang="ts">
-import NetLogoUserManualLogo from '@repo/vue-ui/assets/brands/NetLogoUserManual.svg';
-import TurtlesLogo from '@repo/vue-ui/assets/brands/Turtles.svg';
+import NetLogoUserManualLogo from '@repo/vue-ui/assets/brands/NetLogoUserManual.svg?url';
+import TurtlesLogo from '@repo/vue-ui/assets/brands/Turtles.svg?url';
 import type { Navbar as _Navbar } from '@repo/vue-ui/components/navbar/index';
 import type { VersionProps } from '@repo/vue-ui/widgets/VersionSelectDropdown.vue';
 import { useMediaQuery } from '@vueuse/core';
@@ -60,6 +61,7 @@ import { onVersionChange, pullVersionsFromSource } from '~~/shared/versions';
 const {
   public: {
     website: { productWebsite, productVersion, versionsSrc  },
+    isOffline
   },
 } = useRuntimeConfig();
 
@@ -80,7 +82,10 @@ const extensionList = useRuntimeConfig().public.extensions as Array<{
 const isMobileScreen = ref(false);
 const navbarRef = useTemplateRef<InstanceType<typeof _Navbar>>('navbar');
 
-const brand = computed(() => (isMobileScreen.value ? TurtlesLogo : NetLogoUserManualLogo));
+const brand = computed(() => ( h( 'img', {
+  src: isMobileScreen.value ? TurtlesLogo : NetLogoUserManualLogo,
+  alt: 'NetLogo User Manual',
+})));  
 const brandAttrs = computed(() => (isMobileScreen.value ? { style: { width: '2rem' } } : { width: 'auto' }));
 
 
@@ -229,6 +234,7 @@ const versions = ref<Record<string, VersionProps>>({
 
 const selectedVersion = ref<string>(productVersion);
 
+updateActiveStates();
 onMounted(() => {
   if (import.meta.client) {
     updateActiveStates();

apps/docs/app/components/PrimitiveCatalog/PrimitiveCatalog.vue

@@ -1,5 +1,6 @@
 <template>
-  <SideCatalog
+  <component
+    :is="CatalogComponent"
     :label="dictionaryDisplayName"
     :items="(catalogItems || []) as SideCatalogItem[]"
     item-prefix="primitive:"
@@ -9,6 +10,9 @@
     :scroll-margin-top="150"
     :is-loading="loading"
     with-route-transition
+    :class="{
+      'lg:mt-5 mb-10 px-2 mx-auto nl-container-width min-h-[70vh]': isOffline
+    }"
   >
     <div class="w-full [&>.min-h-screen]:min-h-0 lg:pr-5 pb-10 min-h-rest">
       <slot />
@@ -18,9 +22,9 @@
         <Anchor :href="removeHtmlExtension(dictionaryHomeDirectory)"> {{ dictionaryDisplayName }} </Anchor>.
       </p>
 
-      <Surround :surround="surround" class="mt-auto" />
+      <Surround v-if="!isOffline" :surround="surround" class="mt-auto"/>
     </div>
-  </SideCatalog>
+  </component>
 </template>
 
 <script setup lang="ts">
@@ -31,9 +35,13 @@ import type { CatalogItemData, PrimitiveCatalogProps, SideCatalogItem } from './
 const {
   public: {
     website: { productVersion },
+    isOffline
   },
 } = useRuntimeConfig();
 
+const SideCatalog = resolveComponent('SideCatalog') as typeof import('@repo/vue-ui')['SideCatalog'];
+const CatalogComponent = isOffline ? 'div' : SideCatalog;
+
 const { dictionaryDisplayName, dictionaryHomeDirectory, indexFileURI, currentItemId, currentItemLabel, primRoot } =
   defineProps<PrimitiveCatalogProps>();
 

apps/docs/autogen/3d.md

@@ -164,15 +164,15 @@ end-shape
   One of the first things you will notice when you open NetLogo 3D is that the
   world is a cube instead of a square.
 
-![[3d/cube.png]]
+![[3d/cube.webp]]
 
 You can open up the Model Settings, by clicking on the
 "Settings..." button at the top of the 3D View. You'll notice in
 addition to `max-pxcor`, `min-pxcor`,
 `max-pycor`, and `min-pycor`, there is also
 [[max-pzcor|min-max-pzcor]] and [[min-pzcor|min-max-pzcor]].
 
-![[3d/properties.png]]
+![[3d/properties.webp]]
 
 The z-axis is perpendicular to both the x-axis and the y-axis, when you
 `reset-perspective` it is the axis that comes straight out of the
@@ -220,17 +220,17 @@ Heading, pitch, and roll are turtle variables that represent the orientation
 of the turtle. Heading is absolute in relation to the x/y plane; it is the
 rotation of the turtle around the z-axis.
 
-![[3d/heading.png]]
+![[3d/heading.webp]]
 
 Pitch is the angle between the nose of the turtle and the xy-plane. It is
 relative to heading.
 
-![[3d/pitch.png]]
+![[3d/pitch.webp]]
 
 Roll is the rotation around the turtle's forward vector. It is relative to
 heading and pitch.
 
-![[3d/roll.png]]
+![[3d/roll.webp]]
 
 When turtles are created with `create-turtles` or
 `create-ordered-turtles`, their initial headings vary but their

apps/docs/autogen/behaviorspace.es.md

@@ -492,7 +492,7 @@ En la siguiente imagen de muestra de **Resultados tabulados**, la sección de en
 columnas de número de ejecución (`[run number]`]) y paso (`[step]`) se resaltan en azul, los valores iniciales de las
 variables para la ejecución se muestran en verde y los datos de indicadores de medición se muestran en morado.
 
-![[behaviorspace//behaviorspace/bs-table.png]]
+![[behaviorspace//behaviorspace/bs-table.webp]]
 
 #### Resultados en hoja de cálculo
 
@@ -527,7 +527,7 @@ muestran en verde,
 los indicadores adicionales calculados se muestran en anaranjado, y los datos de medición de indicadores se encuentran
 en morado.
 
-![[behaviorspace//behaviorspace/bs-spreadsheet.png]]
+![[behaviorspace//behaviorspace/bs-spreadsheet.webp]]
 
 #### Resultados estadísticos
 
@@ -550,7 +550,7 @@ En la siguiente imagen de muestra de **Resultados estadísticos**, la sección d
 las combinaciones de parámetros en verde, las columnas de número de paso (`[step]`) en azul, y los datos estadísticos
 morado.
 
-![[behaviorspace//behaviorspace/bs-stats.png]]
+![[behaviorspace//behaviorspace/bs-stats.webp]]
 
 #### Resultados en lista
 
@@ -577,7 +577,7 @@ el nombre del reportero en anaranjado, las columnas de número de ejecución (`[
 (`[step]`)
 en azul, los valores iniciales de las variables en verde, y la lista expandida de datos en morado.
 
-![[behaviorspace//behaviorspace/bs-lists.png]]
+![[behaviorspace//behaviorspace/bs-lists.webp]]
 
 #### Cambios en archivos de resultados
 

apps/docs/autogen/behaviorspace.md

@@ -489,7 +489,7 @@ In the **Table output** sample image below, the header section is in red, the ru
 columns are in blue, the initial values of the variables for the run are in green, and the
 measurement metric data is in purple.
 
-![[behaviorspace/bs-table.png]]
+![[behaviorspace/bs-table.webp]]
 
 #### Spreadsheet output
 This format lists the step numbers as well as each metric for each run in a
@@ -520,7 +520,7 @@ In the **Spreadsheet output** sample image below, the header section is in red,
 is in blue, the initial values of the variables for the run are in green, the extra calculated
 metrics are in orange, and the measurement metric data is in purple.
 
-![[behaviorspace/bs-spreadsheet.png]]
+![[behaviorspace/bs-spreadsheet.webp]]
 
 #### Statistics output
 *(Since 6.4)*
@@ -552,7 +552,7 @@ standard deviation of "count frogs", followed by the same statistics for
 and columns A-D show the parameter combination that was used. The statistics
 are calculated across all the repetitions.
 
-![[behaviorspace/bs-stats.png]]
+![[behaviorspace/bs-stats.webp]]
 
 #### Lists output
 *(Since 6.4)*
@@ -575,7 +575,7 @@ are in green, and the expanded list data is in purple. The list data starts in
 row 7, with the headers (the index into the list, starting from 0) starting in
 column E.
 
-![[behaviorspace/bs-lists.png]]
+![[behaviorspace/bs-lists.webp]]
 
 #### Output File Changes
 *(Since 6.4)*