Website Documentation: Technical Overview

This document provides a concise, developer-friendly guide to the website's architecture, technology stack, and content management practices.

1. Core Technology and Deployment

Our website operates on a static site architecture built for speed and reliability using the following tools:

• Primary Technologies: The site is primarily built with HTML, extended using the Liquid templating language (handled by Jekyll) and client-side logic managed by JavaScript.

• Styling (CSS): All site visuals and layout definitions are centralized in the pre-compiled CSS file located in the assets/ folder. If you need to modify the site's look (colors, fonts, responsiveness, etc.), that is the primary file to adjust.

• Deployment: The site is hosted via GitHub Pages. Deployment is fully automated using GitHub Actions, which triggers a Jekyll build whenever changes are pushed to the main branch.

---

2. Modularity and Reusability

We use Liquid's powerful templating capabilities to prevent repetition and keep the HTML clean.

• Shared Components: Reusable components like the site's main navigation header, footer, and documentation sidebar are stored as modular files in the _includes/ folder.

• Usage: To use these modules, reference them in your HTML file using the Liquid syntax:

  Code snippet

  {% include filename.html %}
  

---

3. The Search Engine System (Critical)

The site features a custom-built, client-side search engine. It relies on a two-part process: offline index creation and online search execution using the Simple-Jekyll-Search library.

A. Data Indexing (search.json file)

This is the offline process that creates the searchable index during the Jekyll build.

• Index Source: The search.json file in the root directory contains Liquid templating logic that iterates over every page.

• Output: It extracts and cleans the relevant text, compiling it into the final searchable index file, _site/search.json.

B. Search Operation (JavaScript)

• Logic: The JavaScript code responsible for handling search queries, filtering results, and generating the result list is found in assets/js/search-script.js. This script handles user input and displays the final output.

C. Content Inclusion and Exclusion Guide

To correctly manage what content appears in the search results:

Action	File to Edit	Instructions
Include a page	Any new HTML file	Add YAML Front Matter (the two lines of --- at the very top) to the page. This tells Jekyll/Liquid to process the file and include it in the index.
Exclude a Page	search.json	Locate point (A) (the {% unless ... %} block). Add the file's URL (e.g., 404.html) to the list following the existing pattern.
Split a Page into Sections	search.json and the page itself	Locate point (B) (the {% if post.url contains ... %} block). Add the page's URL here. Crucially, the content to be indexed must be within a < div class="post-content">... div> block. Use < div class="search-content"> div> between sections as an explicit splitter. Each section must have an < h2> heading for the script to use as a section title.

---

4. Data-Driven Snippets and Examples

To keep documentation files clean and reduce clutter from large code examples, we utilize Jekyll Data Files to store reusable text and code snippets. This ensures consistent formatting and easy updates.

A. System Overview

1. Storage: All documentation examples and code snippets are stored in dedicated YAML files within the _data/ folder.

2. Content Format: Each YAML entry holds the text, which often includes the necessary HTML wrappers for code highlighting (e.g., <pre class='highlight'><code>...</code></pre>).

B. Usage Example

The structure uses Liquid's global site.data variable to access the YAML file's contents.

Component	Example Value	Description
Data file	namelist_examples.yml	The file located in the _data/ directory.
YAML Key	init_grid_description:	The specific key within the YAML file holding the snippet.
Liquid Call	{{ site.data.namelist_examples.init_grid_description }}	This call retrieves the content associated with that key and renders it directly into the page.

Developer Note: To update a code snippet, you only need to edit the corresponding key's value in the YAML file (e.g., _data/namelist_examples.yml).

---

5. Getting Started

A template is provided in the assets/ folder to help you quickly build new documentation pages. It includes comments that further explain required Liquid and HTML structures.