Skip to main content

​
Overview

Poway Auto is built as a Jekyll static site with a modular architecture. The project follows Jekyll conventions with custom JavaScript for API integration and interactive features.

​
Directory Structure

QAV_Frontend/
├── _config.yml              # Jekyll configuration
├── _includes/               # Reusable HTML components
│   ├── nav/                # Navigation components
│   ├── theme/              # Theme-specific includes
│   ├── custom-head.html    # Custom head content
│   ├── submenu.html        # Submenu navigation
│   └── toc.html            # Table of contents
├── _layouts/                # Page templates
│   ├── base.html           # Main layout template
│   ├── post.html           # Blog post layout
│   ├── blogs.html          # Blog listing layout
│   └── schedule.html       # Schedule layout
├── _posts/                  # Blog posts and content
├── _notebooks/              # Jupyter notebooks
├── _data/                   # YAML data files
├── _sass/                   # Sass stylesheets
│   ├── minima/             # Minima theme styles
│   ├── midnight/           # Midnight theme styles
│   └── nighthawk/          # Nighthawk theme styles
├── assets/                  # Static assets
│   └── js/                 # JavaScript files
│       ├── api/            # API integration
│       └── revvit/         # Feature-specific JS
├── navigation/              # Site pages
│   ├── authentication/     # Auth-related pages
│   ├── favoriteLocations/  # Location features
│   └── findBestRoute/      # Route mapping
├── scripts/                 # Build and utility scripts
└── images/                  # Image assets

​
Core Directories

​
Jekyll Directories

​
_includes/

Reusable HTML components that can be included in layouts and pages. Key files:
  • base.html - Base HTML structure
  • custom-head.html - Custom head tags, scripts, and styles
  • submenu.html - Dynamic submenu generation
  • toc.html - Table of contents generator
  • nav/ - Navigation components (login, home, etc.)

​
_layouts/

Page templates that define the structure of different page types. Main layouts:
  • base.html - Primary layout with Tailwind CSS, navigation, and footer
  • post.html - Blog post template with metadata
  • blogs.html - Blog listing page
  • schedule.html - Schedule and calendar views
The base layout (_layouts/base.html:1-175) includes:
  • Tailwind CSS configuration
  • Dark mode toggle
  • Responsive navigation
  • User authentication status
  • Alpine.js for interactivity

​
_posts/

Markdown or HTML files for blog posts and content pages. Posts follow the naming convention: 
YYYY-MM-DD-title.md
Examples:
  • 2024-09-19-bathroom_pass.md
  • 2024-11-05-GenresChatroom.md
  • 2025-04-08-planning.md

​
_notebooks/

Jupyter notebooks that are automatically converted to Markdown posts during the build process. The conversion is handled by scripts/convert_notebooks.py.

​
_data/

YAML files containing structured data accessible via site.data in templates. Available data files:
  • submenu.yml - Submenu configuration
  • csa.yml, csp.yml, csse.yml - Course-specific data
  • mario_metadata.yml - Game metadata
  • alienWorld.yml - Feature configuration

​
Asset Directories

​
assets/js/

JavaScript modules for client-side functionality. Structure: 
assets/js/
├── api/
│   ├── config.js          # API configuration and fetch utilities
│   ├── login.js           # Login functionality
│   └── profile.js         # User profile management
├── revvit/
│   ├── carChat.js         # Car chat features
│   └── myCar.js           # Car management
├── cookies.js             # Cookie utilities
├── search.js              # Site search
└── vendor/                # Third-party libraries

​
_sass/

Sass/SCSS stylesheets organized by theme. Theme structure: 
_sass/
├── minima/                # Minima theme (primary)
│   ├── custom-styles.scss
│   ├── custom-variables.scss
│   ├── dracula/           # Dracula color scheme
│   ├── hacker/            # Hacker theme
│   └── hamilton/          # Hamilton theme
├── midnight/              # Midnight theme
└── nighthawk/             # Nighthawk theme
The navigation/ directory contains feature pages organized by functionality: 
navigation/
├── authentication/        # Auth pages
│   ├── login.md
│   ├── logout.md
│   ├── profile.md
│   └── admin.md
├── favoriteLocations/     # Location management
├── findBestRoute/         # Route planning
│   ├── findBestRoute.md
│   ├── map.js
│   └── map.css
├── verify.html            # Location verification
├── traffic.html           # Traffic information
└── dailyroutine.html      # Daily routine features

​
Build System

​
Makefile

The project uses a Makefile (Makefile:1-143) for development and build automation. Key targets: 
# Start development server (default port 4887)
make
make PORT=4200

# Convert notebooks to markdown
make convert

# Clean generated files
make clean

# Stop server
make stop
Configuration variables:
  • PORT - Server port (default: 4887)
  • REPO_NAME - Repository name (default: flocker_frontend)
  • LOG_FILE - Jekyll log location (/tmp/jekyll.log)

​
Scripts

​
scripts/convert_notebooks.py

Converts Jupyter notebooks to Jekyll-compatible Markdown with front matter extraction. Automatically triggered when notebooks change during development. Conversion process:
  1. Extracts YAML front matter from notebook cells
  2. Converts notebook to Markdown using nbconvert
  3. Saves to _posts/ with _IPYNB_2_.md suffix
  4. Preserves directory structure

​
Configuration Files

​
.gitignore

Excludes build artifacts, dependencies, and sensitive files:
  • _site/ - Jekyll build output
  • .sass-cache/ - Sass compilation cache
  • node_modules/ - npm dependencies
  • .env - Environment variables

​
Gemfile

Ruby dependencies for Jekyll: 
source "https://rubygems.org"

gem "github-pages", group: :jekyll_plugins
gem "webrick", "~> 1.7"
gem "execjs", "~> 2.8"

​
requirements.txt

Python dependencies for notebook conversion and utilities.

​
Development Workflow

​
Starting Development

  1. Install dependencies: 
    bundle install          # Ruby gems
pip install -r requirements.txt  # Python packages
  2. Start the server: 
    make                    # Default port 4887
  3. Access the site: 
    http://127.0.0.1:4887/QAV_Frontend/

​
Adding New Pages

Static page: 
touch navigation/new-page.md
Blog post: 
touch _posts/2025-03-04-my-post.md
Jupyter notebook: 
# Add to _notebooks/
# Will auto-convert on save during development

​
File Naming Conventions

  • Posts: YYYY-MM-DD-title.md
  • Notebooks: *.ipynb (converted to *_IPYNB_2_.md)
  • Pages: descriptive-name.md or .html
  • Layouts: lowercase.html
  • Includes: lowercase-hyphenated.html
  • Data: lowercase.yml

​
Next Steps

API Integration

Learn about backend API setup and fetch patterns

Configuration

Explore configuration options and environment setup

Build docs developers (and LLMs) love

Get started for freeTalk to us