[docs] Fix docs.opencue.io redirect and broken asset paths and docs improvements (AcademySoftwareFoundation#1818)

The documentation site failed after redirecting from
academysoftwarefoundation.github.io/OpenCue to docs.opencue.io due to
hardcoded `/OpenCue/` paths.

Updates include:
- Changed Jekyll `baseurl` from "/OpenCue" to "" for root domain hosting
- Replaced hardcoded `/OpenCue/` paths with Jekyll’s `relative_url`
filter
- Updated GitHub Actions to support both docs.opencue.io and GitHub
Pages deployments
- Fixed asset references in CSS, JavaScript, and markdown
- Updated documentation links in README files
- Modified build.sh to auto-detect baseurl configuration

The site now loads correctly on:
- docs.opencue.io (production)
- GitHub Pages forks (auto `/OpenCue` baseurl)

Resolves formatting and navigation issues reported by the Linux
Foundation.

Other changes:
- Merge master latest changes: [docs] Add Previous/Next navigation
buttons and Docs link to documentation
- Fix monospace font rendering for code blocks in documentation
- Fixed "Get Started" button on homepage: Updated link from
/docs/quick-starts/ to /docs/getting-started/
- Added active development notice to docs `index` and `getting-started`
pages with links to master branch, sandbox guide, and upcoming release
info.

**Link the Issue(s) this Pull Request is related to.**
- AcademySoftwareFoundation#1800

Author: ramonfigueiredo

.github/workflows/docs.yml

@@ -121,10 +121,17 @@ jobs:
           echo "build_date: ${{ steps.version.outputs.build_date }}" >> _config.yml
           echo "opencue_version: ${{ steps.version.outputs.opencue_version }}" >> _config.yml
           
-          if [ "${{ github.event_name }}" = "pull_request" ]; then
+          # Determine baseurl based on deployment target
+          # For docs.opencue.io deployment, use empty baseurl
+          # For GitHub Pages in forks, use /OpenCue
+          if [ "${{ github.repository }}" = "AcademySoftwareFoundation/OpenCue" ]; then
+            # Main repository - deploying to docs.opencue.io
+            bundle exec jekyll build --baseurl ""
+          elif [ "${{ github.event_name }}" = "pull_request" ]; then
+            # Pull request - use GitHub Pages path
             bundle exec jekyll build --baseurl "/OpenCue"
           else
-            # For versioned builds, add version to path
+            # Fork or other deployment - use GitHub Pages path
             if [ "${{ steps.version.outputs.version }}" != "main" ]; then
               bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}/${{ steps.version.outputs.version }}"
             else

README.md

@@ -95,9 +95,9 @@ If you make changes to `OpenCue/docs`, please build and test the documentation b
 
 For detailed documentation setup instructions, testing procedures, and contribution guidelines, see [docs/README.md](https://github.com/AcademySoftwareFoundation/OpenCue/blob/master/docs/README.md).
 
-**Note:** Once your pull request is merged into master, the documentation will be automatically deployed via GitHub Actions ([.github/workflows/docs.yml](https://github.com/AcademySoftwareFoundation/OpenCue/blob/master/.github/workflows/docs.yml)). The updated documentation will be available at https://academysoftwarefoundation.github.io/OpenCue/.
+**Note:** Once your pull request is merged into master, the documentation will be automatically deployed via GitHub Actions ([.github/workflows/docs.yml](https://github.com/AcademySoftwareFoundation/OpenCue/blob/master/.github/workflows/docs.yml)). The updated documentation will be available at https://docs.opencue.io/.
 
-The new OpenCue documentation will soon replace the current version at https://www.opencue.io.
+The OpenCue documentation is now available at https://docs.opencue.io/.
 
 # Meeting notes
 

docs/README.md

@@ -32,7 +32,7 @@ This directory contains the official documentation for OpenCue, built with Jekyl
    bundle exec jekyll serve --livereload
    ```
 
-5. **Open in browser:** http://localhost:4000/OpenCue
+5. **Open in browser:** http://localhost:4000/
 
 ## Documentation Structure
 
@@ -106,7 +106,7 @@ The documentation supports advanced Markdown features:
 1. **Place images** in `assets/images/`
 2. **Reference with proper baseurl:**
    ```markdown
-   ![Alt text](/OpenCue/assets/images/your-image.png)
+   ![Alt text]({{ '/assets/images/your-image.png' | relative_url }})
    ```
 3. **Use descriptive alt text** for accessibility
 
@@ -249,7 +249,7 @@ Documentation is automatically deployed via GitHub Actions:
 2. **Workflow:** `.github/workflows/docs.yml`
 3. **Build environment:** Ubuntu with Ruby 3.x
 4. **Deployment target:** GitHub Pages
-5. **URL:** `https://academysoftwarefoundation.github.io/OpenCue` (will be changed to `https://opencue.io` in the future)
+5. **URL:** `https://docs.opencue.io` (redirected from `https://academysoftwarefoundation.github.io/OpenCue`)
 
 ### Deploying Documentation in Your Fork
 
@@ -268,6 +268,7 @@ For developers contributing to the OpenCue project who want to validate the Open
    - Go to the Actions tab
    - Find the "Deploy Documentation" workflow and either re-run it or manually trigger it to publish your docs
    - Your documentation will be available at `https://[your-username].github.io/OpenCue`
+   - Note: In your fork, you may need to update `baseurl` in `_config.yml` to `/OpenCue` for GitHub Pages
 
 ### Build Process
 
@@ -282,8 +283,8 @@ For developers contributing to the OpenCue project who want to validate the Open
 Key configuration for deployment:
 ```yaml
 # _config.yml
-baseurl: "/OpenCue"                                    # GitHub Pages path
-url: "https://academysoftwarefoundation.github.io"    # Base domain
+baseurl: ""                                    # Empty for root domain hosting
+url: "https://docs.opencue.io"                # Production domain
 ```
 
 ## Contributing
@@ -332,7 +333,7 @@ bundle install
 
 
 **Images not displaying:**
-- Ensure proper baseurl (`/OpenCue/assets/images/`)
+- Ensure proper baseurl usage (`{{ '/assets/images/' | relative_url }}`)
 - Check file paths and case sensitivity
 - Verify images exist in `assets/images/`
 

docs/_config.yml

@@ -1,8 +1,8 @@
 # OpenCue Documentation Configuration
 title: OpenCue Documentation
 description: OpenCue is an open source render management system for visual effects and animation.
-baseurl: "/OpenCue" # the subpath of your site, e.g. /blog
-url: "https://academysoftwarefoundation.github.io" # the base hostname & protocol for your site
+baseurl: "" # the subpath of your site, e.g. /blog
+url: "https://docs.opencue.io" # the base hostname & protocol for your site
 
 # Build settings
 theme: just-the-docs
@@ -37,8 +37,8 @@ doc_version: "0.0.1"
 
 # Just the Docs theme configuration
 color_scheme: nil
-logo: "/assets/images/opencue_logo_with_text.png"
-favicon_ico: "/assets/images/favicon.ico"
+logo: "assets/images/opencue_logo_with_text.png"
+favicon_ico: "assets/images/favicon.ico"
 
 
 
@@ -72,7 +72,7 @@ aux_links_new_tab: true
 footer_content: |
   <div style="display: flex; align-items: center; justify-content: center; gap: 2rem; flex-wrap: wrap; margin: 1rem 0;">
     <a href="https://www.aswf.io" target="_blank">
-      <img src="/OpenCue/assets/images/aswf_aqua.png" alt="Academy Software Foundation logo" style="height: 60px; width: auto;">
+      <img src="{{ '/assets/images/aswf_aqua.png' | relative_url }}" alt="Academy Software Foundation logo" style="height: 60px; width: auto;">
     </a>
     <div style="text-align: center;">
       <p style="margin: 0; font-size: 0.9rem;">© Contributors to the OpenCue Project. Licensed under <a href="https://github.com/AcademySoftwareFoundation/OpenCue/blob/master/LICENSE">Apache 2.0</a>.</p>

docs/_docs/getting-started/index.md

@@ -9,3 +9,12 @@ permalink: /docs/getting-started
 # OpenCue getting started guide
 
 Guides for system admins deploying OpenCue components and installing dependencies
+
+## All OpenCue documentation
+
+---
+
+🚧 **Note:** Documentation is currently under active development. 
+
+- Please use the latest version from the [Opencue master branch](https://github.com/AcademySoftwareFoundation/OpenCue) for the moment. We are working to release a new version of OpenCue soon.
+- For quick start on Linux or macOS, follow the guide [Using the OpenCue Sandbox for Testing](developer-guide/sandbox-testing/)

docs/_docs/index.md

@@ -8,7 +8,7 @@ permalink: /docs/
 
 <div class="mx-auto text-center">
     <div style="display: flex; align-items: center; justify-content: center; gap: 20px;">
-        <img src="/OpenCue/assets/images/opencue-icon-black.svg" alt="OpenCue" style="height: 140px; background-color: white; padding: 10px; border-radius: 8px;">
+        <img src="{{ '/assets/images/opencue-icon-black.svg' | relative_url }}" alt="OpenCue" style="height: 140px; background-color: white; padding: 10px; border-radius: 8px;">
         <div style="text-align: center;">
             <h1 class="display-4" style="margin: 0;">OpenCue</h1>
             <h3 class="lead" style="margin: 0;">An open source render management system</h3>
@@ -21,16 +21,25 @@ permalink: /docs/
         <a class="btn btn-lg btn-black" style="margin: 5px;" href="https://lf-aswf.atlassian.net/wiki/spaces/OPENCUE/overview">
             <i class="fab fa-slack"></i>&nbsp;Participate
         </a>
-        <a class="btn btn-lg btn-dark" style="margin: 5px;" href="/OpenCue/docs/">
+        <a class="btn btn-lg btn-dark" style="margin: 5px;" href="{{ '/docs/' | relative_url }}">
             <i class="fas fa-book"></i>&nbsp;Documentation
         </a>
-        <a class="btn btn-lg btn-black" style="margin: 5px;" href="/OpenCue/news/">
+        <a class="btn btn-lg btn-black" style="margin: 5px;" href="{{ '/news/' | relative_url }}">
             <i class="fas fa-newspaper"></i>&nbsp;News
         </a>
     </div>
 </div>
 
-All OpenCue documentation
+## All OpenCue documentation
+
+---
+
+🚧 **Note:** Documentation is currently under active development. 
+
+- Please use the latest version from the [Opencue master branch](https://github.com/AcademySoftwareFoundation/OpenCue) for the moment. We are working to release a new version of OpenCue soon.
+- For quick start on Linux or macOS, follow the guide [Using the OpenCue Sandbox for Testing](developer-guide/sandbox-testing/)
+
+---
 
 ### [Quick starts](quick-starts/)
 

docs/_includes/header_custom.html

@@ -1261,7 +1261,7 @@
 <style>
   /* Fix logo size and visibility */
   .site-logo {
-    background-image: url('/OpenCue/assets/images/opencue_logo_with_text.png');
+    background-image: url('{{ "/assets/images/opencue_logo_with_text.png" | relative_url }}');
     background-size: contain;
     background-repeat: no-repeat;
     background-position: center;
@@ -1337,6 +1337,30 @@
     color: #24292e !important;
   }
 
+  /* Code blocks - ensure monospace font for all modes */
+  code {
+    font-family: 'JetBrains Mono', 'Fira Code', 'Consolas', 'Monaco', 'Courier New', monospace !important;
+    font-size: 0.875em;
+  }
+  
+  pre {
+    font-family: 'JetBrains Mono', 'Fira Code', 'Consolas', 'Monaco', 'Courier New', monospace !important;
+  }
+  
+  pre code {
+    font-family: inherit !important;
+  }
+  
+  /* Ensure proper formatting for ASCII art and aligned text */
+  .highlight pre,
+  .highlighter-rouge pre,
+  .language-plaintext {
+    font-family: 'JetBrains Mono', 'Fira Code', 'Consolas', 'Monaco', 'Courier New', monospace !important;
+    white-space: pre !important;
+    word-wrap: normal !important;
+    overflow-x: auto !important;
+  }
+  
   /* Buttons - use dark gray theme */
   .btn-primary {
     background-color: #374151 !important;
@@ -1825,21 +1849,23 @@
     border: 1px solid #6b7280 !important;
     border-radius: 4px;
     padding: 2px 6px;
-    font-family: 'JetBrains Mono', 'Fira Code', monospace;
+    font-family: 'JetBrains Mono', 'Fira Code', 'Consolas', 'Monaco', 'Courier New', monospace !important;
   }
 
   body.dark-mode pre {
     background: #1f2937 !important;
     color: #e5e7eb !important;
     border: 1px solid #4b5563 !important;
     border-radius: 8px;
+    font-family: 'JetBrains Mono', 'Fira Code', 'Consolas', 'Monaco', 'Courier New', monospace !important;
   }
 
   body.dark-mode pre code {
     color: #e5e7eb !important;
     border: none !important;
     background: transparent !important;
     padding: 0;
+    font-family: inherit !important;
   }
 
   /* Professional table design */

docs/assets/js/search.js

@@ -27,7 +27,8 @@
   // Load search data
   function loadSearchData() {
     var xhr = new XMLHttpRequest();
-    xhr.open('GET', '/OpenCue/search-data.json');
+    var baseUrl = document.querySelector('base') ? document.querySelector('base').getAttribute('href') : '';
+    xhr.open('GET', (baseUrl || '') + '/search-data.json');
     xhr.onload = function() {
       if (xhr.status === 200) {
         searchData = JSON.parse(xhr.responseText);

docs/build.sh

@@ -116,11 +116,11 @@ else
     print_warning "Theme toggle functionality not found in index.html"
 fi
 
-# Check for proper image paths
-if grep -q "/OpenCue/assets/images/" _site/**/*.html 2>/dev/null; then
-    print_success "Proper image paths with baseurl found"
+# Check for proper image paths - now checking for relative_url filter usage
+if grep -q "assets/images/" _site/**/*.html 2>/dev/null; then
+    print_success "Image paths found in build output"
 else
-    print_warning "Image paths may not include proper baseurl"
+    print_warning "No image paths found in build output"
 fi
 
 # Build size information
@@ -136,7 +136,13 @@ echo -e "Build output: ${BLUE}$(pwd)/_site${NC}"
 echo ""
 print_status "Testing options:"
 echo "- Serve locally:     bundle exec jekyll serve"
-echo "- Local URL:         http://localhost:4000/OpenCue/"
+# Determine the local URL based on baseurl setting
+if grep -q 'baseurl: ""' _config.yml; then
+    echo "- Local URL:         http://localhost:4000/"
+else
+    baseurl=$(grep 'baseurl:' _config.yml | sed 's/.*baseurl: "\(.*\)"/\1/')
+    echo "- Local URL:         http://localhost:4000${baseurl}/"
+fi
 echo "- Validate HTML:     bundle exec htmlproofer _site --disable-external"
 echo "- Test dark mode:    Open site and click sun/moon icon in top-right"
 

docs/docs.md

@@ -11,26 +11,26 @@ Comprehensive documentation for OpenCue, including installation guides, tutorial
 
 ## Documentation Sections
 
-### [Quick Starts](/OpenCue/docs/quick-starts/)
+### [Quick Starts]({{ '/docs/quick-starts/' | relative_url }})
 Get OpenCue running quickly with our sandbox environments for Linux, macOS, and Windows.
 
-### [Concepts](/OpenCue/docs/concepts/)
+### [Concepts]({{ '/docs/concepts/' | relative_url }})
 Learn about OpenCue's architecture, components, and core principles.
 
-### [Getting Started](/OpenCue/docs/getting-started/)
+### [Getting Started]({{ '/docs/getting-started/' | relative_url }})
 Production deployment guides for system administrators and DevOps teams.
 
-### [User Guides](/OpenCue/docs/user-guides/)
+### [User Guides]({{ '/docs/user-guides/' | relative_url }})
 Day-to-day workflows for artists, supervisors, and production staff.
 
-### [Other Guides](/OpenCue/docs/other-guides/)
+### [Other Guides]({{ '/docs/other-guides/' | relative_url }})
 Advanced configuration, troubleshooting, and administrative guides.
 
-### [Developer Guide](/OpenCue/docs/developer-guide/)
+### [Developer Guide]({{ '/docs/developer-guide/' | relative_url }})
 Resources for developers contributing to OpenCue or building integrations.
 
-### [Reference](/OpenCue/docs/reference/)
+### [Reference]({{ '/docs/reference/' | relative_url }})
 Complete reference documentation for all OpenCue tools, APIs, and interfaces.
 
-### [Tutorials](/OpenCue/docs/tutorials/)
+### [Tutorials]({{ '/docs/tutorials/' | relative_url }})
 Step-by-step tutorials for learning OpenCue workflows and best practices.