pages/.github/instructions/javascript-scripts.instructions.md

applyTo
_scripts/**/*.js

JavaScript Scripts Instructions

Overview

The _scripts/ directory contains JavaScript files that provide frontend functionality for the al-folio website. These scripts handle:

• Search functionality – Ninja-keys integration for search bar
• Analytics setup – Google Analytics, Cronitor, Open Panel integrations
• Gallery functionality – PhotoSwipe lightbox initialization
• Liquid template processing – Files with .liquid.js extension process Jekyll Liquid syntax

Key Script Files

search.liquid.js

• Purpose: Generates searchable navigation data for the Ninja-keys search component
• Type: Liquid + JavaScript hybrid (Jekyll processes .liquid.js files)
• Output: Compiled to /assets/js/search-data.js via permalink frontmatter
• Content: Builds ninja.data array from site pages, posts, and navigation structure
• Usage: Included in _includes/scripts.liquid and loaded in layouts

photoswipe-setup.js

• Purpose: Initializes PhotoSwipe lightbox for image galleries
• Type: Pure JavaScript with ES6 imports
• Output: Compiled to /assets/js/photoswipe-setup.js
• Dependencies: PhotoSwipe library (referenced via site.third_party_libraries)
• Functionality: Automatically converts .pswp-gallery elements into interactive lightbox galleries

google-analytics-setup.js, cronitor-analytics-setup.js, open-panel-analytics-setup.js

• Purpose: Initialize third-party analytics services
• Type: Conditional setup scripts (may be excluded from production builds)
• Usage: Loaded conditionally based on _config.yml feature flags
• Integration: Each sets up tracking code for respective analytics platforms

File Structure & Frontmatter

All scripts in _scripts/ may include Jekyll frontmatter:

---
permalink: /assets/js/filename.js
---
// JavaScript code here

Key frontmatter fields:

• permalink: – Specifies output path in compiled site (e.g., /assets/js/search-data.js)
• Comments/empty – Files with only JavaScript and no frontmatter are processed as-is

Processing:

• .liquid.js files – Processed by Jekyll's Liquid engine before JavaScript compilation
• .js files – Processed normally, passed through to assets directory
• Note: Files in _scripts/ are ignored by Prettier (see .prettierignore) because .liquid.js files mix Liquid template syntax with JavaScript, which Prettier doesn't support

JavaScript Patterns in al-folio

Liquid + JavaScript Mixing (in .liquid.js files)

Example from search.liquid.js:

---
permalink: /assets/js/search-data.js
---
// Regular JavaScript
const ninja = document.querySelector('ninja-keys');

// Liquid processing - Jekyll loops and variables
ninja.data = [
  {%- for page in site.pages -%}
    {
      id: "nav-{{ page.title | slugify }}",
      title: "{{ page.title }}",
      handler: () => {
        window.location.href = "{{ page.url | relative_url }}";
      },
    },
  {%- endfor -%}
];

Important:

• Use Liquid filters (| slugify, | relative_url, | escape) to process Jekyll variables
• Curly braces {{ }} output variables
• Use {%- -%} (with hyphens) to control whitespace in generated output
• Keep JSON structures valid after Liquid processing

ES6 Modules & Imports

Scripts use modern JavaScript with ES6 imports:

import PhotoSwipeLightbox from "{{ site.third_party_libraries.photoswipe-lightbox.url.js }}";
import PhotoSwipe from "{{ site.third_party_libraries.photoswipe.url.js }}";

• Import third-party libraries via site.third_party_libraries configuration
• Libraries resolved from _config.yml CDN or local paths

DOM Manipulation & Event Handlers

Scripts attach to specific DOM elements:

const element = document.querySelector(".selector");
element.addEventListener("click", (event) => {
  // Handle event
});

Common Modification Patterns

Adding a New Analytics Service

1. Create new file _scripts/myservice-setup.js:

---
permalink: /assets/js/myservice-setup.js
---
(function() {
  // Initialize your service
  if (window.myService) {
    console.log('MyService loaded');
  }
})();

2. Add conditional loading to _includes/scripts.liquid:

{% if site.myservice_enabled %}
  <script src="{{ '/assets/js/myservice-setup.js' | relative_url }}"></script>
{% endif %}

3. Add feature flag to _config.yml:

myservice_enabled: false

Modifying Search Data Structure

In search.liquid.js:

1. Identify the Liquid loop building ninja.data array
2. Add new properties to each object:

{
  id: "nav-{{ title | slugify }}",
  title: "{{ title }}",
  newField: "{{ page.new_property }}",  // Add new field
  handler: () => { ... }
}

3. Rebuild: docker compose up will regenerate /assets/js/search-data.js

Updating Gallery Functionality

In photoswipe-setup.js:

1. Modify gallery selector or initialization options
2. Reference PhotoSwipe documentation for available options
3. Update any CSS classes used in gallery markup

Code Style Notes

Prettier and _scripts/:

Files in _scripts/ are excluded from Prettier formatting (defined in .prettierignore) because:

• .liquid.js files contain mixed Liquid template syntax and JavaScript
• Prettier doesn't understand or support this hybrid format
• Manual formatting consistency is required for these files

When modifying _scripts/ files:

• Follow existing code style in the file (indentation, spacing, quotes)
• Maintain readability for Liquid + JavaScript mixed code
• Do NOT run Prettier on the _scripts/ directory
• DO run Prettier on the rest of the project when making other changes: npx prettier . --write

Validation & Testing

Local Build Test

docker compose up
# Wait 30 seconds for Jekyll to build
# Check for errors in terminal output
# Visit http://localhost:8080 and verify functionality

Checking Generated Output

After docker compose up, verify scripts compiled correctly:

# Check if script files exist in _site/assets/js/
ls _site/assets/js/

# Verify no Liquid syntax in generated output (should be pure JavaScript)
cat _site/assets/js/search-data.js | head -20

Debugging Script Issues

Script not loading:

• Check browser DevTools Console for HTTP 404 errors
• Verify permalink: frontmatter matches script inclusion paths
• Check that script is actually in _site/assets/js/ after build

Liquid syntax errors:

• Jekyll build will fail with "Liquid Exception" messages
• Check file for unclosed {% %} or {{ }} tags
• Ensure Liquid filters exist (| relative_url, | slugify, etc.)

JavaScript errors:

• Check browser console for runtime errors
• Verify all imported libraries are defined in site.third_party_libraries in _config.yml
• Test in both Chrome and Firefox for compatibility

Trust These Instructions

When modifying JavaScript scripts:

• .liquid.js files must have valid Liquid syntax AND valid JavaScript that remains valid after Jekyll processes the Liquid
• Do NOT run Prettier on _scripts/ files (they are in .prettierignore because of Liquid + JavaScript mixing)
• Test locally with docker compose up to verify build succeeds and scripts work
• For site-wide script inclusion, modify _includes/scripts.liquid
• For configuration (feature flags, third-party URLs), see yaml-configuration.instructions.md
• Reference the actual script files in _scripts/ as examples when adding new functionality
• Only search for additional details if errors occur during build or testing