Architecture

This guide explains the architecture of the Analytiq Pages Starter and how it integrates with the Analytiq Pages Theme.

Overview

The starter is built on Jekyll with a modular theme-based architecture that separates presentation (theme) from content (site). The theme provides layouts, styling, and reusable components, while the starter contains your site-specific content, configuration, and any customizations.

Loading diagram...

Edit diagram

Component Architecture

Site Structure (Starter)

The starter repository contains your site-specific content and configuration:

Content Files: Markdown files for pages, blog posts, and documentation stored at the root level
Configuration: _config.yml defines site metadata, navigation, pagination, and theme settings
Site-Specific Overrides: Custom includes (like docs-widget.html) that override theme defaults
Static Assets: Images, documents, and other media files in assets/
Blog Posts: Posts stored in _posts/ directory with date-prefixed filenames
Collections: Posts collection configured for blog functionality

Theme Layer (Analytiq Pages Theme)

The theme provides the presentation layer:

Layouts: HTML templates for different page types (default, page, post, docs)
Includes: Reusable components (header, footer, navigation)
Assets: CSS, JavaScript, and common images
Tailwind CSS: Styling framework via CDN
Excalidraw Integration: Support for rendering Excalidraw diagrams

How It Works

1. Theme Inheritance

# Gemfile
gem "analytiq-pages-theme",
    git: "https://github.com/analytiq-hub/analytiq-pages-theme.git",
    tag: "v0.1.8"

Jekyll loads the theme from the Git repository (version v0.1.8), making all theme assets available to your site. The theme is specified in _config.yml:

theme: analytiq-pages-theme

2. Override Mechanism

Your site can override any theme file by creating a file with the same path:

analytiq-pages-starter/
├── _includes/
│   └── docs-widget.html      # Overrides theme's docs-widget
├── _layouts/                  # Custom layouts (if needed)
│   └── custom.html
└── assets/
    └── images/                # Site-specific images
        └── blog/              # Blog post images

The starter currently overrides docs-widget.html to provide custom documentation navigation.

3. Content Rendering Flow

Request: User visits a page (e.g., /docs/getting-started/)
Content Load: Jekyll finds the markdown file (docs/getting-started.md)
Layout Application: Uses the layout specified in front matter (layout: docs)
Theme Resolution: Looks for layout in site first, then in theme
Includes Processing: Processes all include directives from theme and site overrides
Override Check: Uses site’s include if it exists, otherwise theme’s
HTML Generation: Converts markdown to HTML and applies layout
Static Output: Generates final HTML file in _site/ directory

Key Features

Responsive Design

The theme uses Tailwind CSS with a mobile-first approach:

Breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px)
Flexible Layouts: Flexbox and Grid for complex layouts
Typography Plugin: Prose classes for beautiful markdown rendering
CDN Delivery: Tailwind CSS loaded via CDN for fast performance

Documentation System

The docs layout provides a specialized environment for documentation:

Sidebar Widget: Custom navigation menu via _includes/docs-widget.html override
Prose Styling: Enhanced markdown rendering with proper spacing
Code Highlighting: Syntax highlighting for code blocks
Responsive Layout: Sidebar collapses on mobile devices
Excalidraw Diagrams: Support for embedding Excalidraw diagrams via excalidraw-wrapper divs

Blog System

Built-in blog with pagination support:

Collections: Posts organized as a Jekyll collection
Pagination: Uses jekyll-paginate-v2 plugin (5 posts per page)
Categories: Organize posts by category (e.g., “company announcements”, “engineering”)
RSS Feed: Automatic feed generation with jekyll-feed
Post Previews: Excerpt support with images
Permalink Structure: Posts use /:categories/:title/ permalink format

Plugins

The starter uses the following Jekyll plugins:

jekyll-feed: Generates RSS feed for blog posts
jekyll-seo-tag: Adds SEO meta tags to pages
jekyll-pdf-embed: Allows embedding PDF files in pages
jekyll-paginate-v2: Advanced pagination for blog and other pages

Configuration

Site Configuration (`_config.yml`)

Key configuration sections:

# Site Metadata
title: Your Company Name
author:
  name: Your Name
  email: "hello@yourcompany.com"
description: Your company description

# Theme
theme: analytiq-pages-theme

# Navigation
header_pages:
  - title: "Products"
    url: "#"
    children:
      - title: "Overview"
        url: "/products"
      - title: "Features"
        url: "/features"

# Collections
collections:
  posts:
    output: true
    permalink: /:categories/:title/

# Pagination
pagination:
  enabled: true
  per_page: 5
  permalink: '/page/:num/'
  sort_field: 'date'
  sort_reverse: true

# Plugins
plugins:
  - jekyll-feed
  - jekyll-seo-tag
  - jekyll-pdf-embed
  - jekyll-paginate-v2

Theme Customization

You can customize the theme without modifying it:

Override Includes: Create _includes/filename.html in your site (e.g., docs-widget.html)
Override Layouts: Create _layouts/filename.html in your site
Add Custom CSS: Include custom styles in _includes/custom-head.html
Extend JavaScript: Add scripts via custom includes

Deployment Architecture

GitHub Pages Deployment

The starter includes a GitHub Actions workflow (.github/workflows/pages.yml) for automatic deployment:

Loading diagram...

Edit diagram

Build Process

Dependency Resolution: Bundler downloads the theme gem (v0.1.8) from GitHub
Theme Installation: Theme files are available to Jekyll
Site Build: Jekyll processes all content and applies theme
Asset Processing: Copies assets, processes includes
Static Generation: Creates static HTML files in _site/
Artifact Upload: GitHub Actions uploads _site/ as artifact
Deployment: GitHub Pages serves the static files

GitHub Actions Workflow

The workflow runs on:

Push to main branch
Manual workflow dispatch

It uses:

Ruby 3.2
Bundler cache for faster builds
GitHub Pages deployment action
Production environment for optimized builds

File Organization

Actual Structure

analytiq-pages-starter/
├── _config.yml              # Site configuration
├── _includes/               # Site-specific includes (overrides)
│   └── docs-widget.html    # Custom docs navigation widget
├── _posts/                  # Blog posts collection
│   ├── 2025-11-01-welcome-to-our-blog.md
│   ├── 2025-11-15-building-scalable-systems.md
│   └── 2025-11-22-api-design-best-practices.md
├── docs/                    # Documentation pages
│   ├── getting-started.md
│   ├── user-guide.md
│   ├── api-reference.md
│   └── architecture.md
├── assets/                  # Static assets
│   ├── excalidraw/          # Excalidraw diagram files
│   │   └── analytiq-pages-architecture.excalidraw
│   └── images/
│       └── blog/            # Blog post images
│           ├── welcome.svg
│           ├── scalable-systems.svg
│           └── api-design.svg
├── .github/
│   └── workflows/
│       └── pages.yml        # GitHub Actions deployment workflow
├── index.md                 # Homepage
├── about.md                 # About page
├── contact.md               # Contact page
├── products.md              # Products overview
├── features.md              # Features page
├── case-studies.md          # Case studies
├── blog.md                  # Blog listing page
├── talks.md                 # Talks page
├── 404.html                 # Custom 404 page
├── favicon.ico              # Site favicon
├── Gemfile                  # Ruby dependencies
├── Gemfile.lock             # Locked dependency versions
├── LICENSE                  # License file
├── Makefile                 # Build shortcuts
└── README.md                # Project documentation

Content Organization

Root-level Pages: Main site pages (index, about, contact, etc.) are markdown files at the root
Documentation: All docs pages in docs/ directory with layout: docs
Blog Posts: Posts in _posts/ with date prefix (YYYY-MM-DD-title.md)
Assets: Images organized by purpose (blog images in assets/images/blog/)

Best Practices

Content Organization

Use Permalinks: Define explicit permalinks in front matter for consistent URLs
Consistent Naming: Use kebab-case for file names
Category Hierarchy: Organize posts by category (space-separated in front matter)
Asset Management: Keep images close to content in /assets/images/
Front Matter: Always include layout, title, and permalink in front matter

Theme Customization

Minimal Overrides: Only override what you need to change (currently just docs-widget.html)
Document Changes: Comment why you’re overriding theme files
Version Control: Track theme version in Gemfile for reproducibility (currently v0.1.8)
Test Locally: Always test changes with bundle exec jekyll serve

Performance

Image Optimization: Compress images before adding to repository
SVG for Icons: Use SVG for logos and icons (as seen in blog images)
Minimal Dependencies: Only include necessary Jekyll plugins
CDN Usage: Leverage CDN for third-party resources (Tailwind, fonts)
Static Generation: All pages are pre-rendered for fast loading

Extending the Starter

Adding a New Page

Create a markdown file at the root (e.g., services.md)

Add front matter with layout and permalink:

---
layout: page
title: Services
permalink: /services/
---

Add navigation link in _config.yml under header_pages

Adding a New Documentation Section

Create markdown file in docs/ directory (e.g., docs/troubleshooting.md)

Set front matter with layout: docs and permalink:

---
layout: docs
title: Troubleshooting
permalink: /docs/troubleshooting/
---

Add link to _includes/docs-widget.html navigation
Content will automatically use docs layout with sidebar

Adding a Blog Post

Create file in _posts/ with format: YYYY-MM-DD-post-title.md

Include front matter:

---
layout: post
title: "Your Post Title"
date: 2025-11-29 10:00:00 -0400
categories: category1 category2
author: "Author Name"
image: /assets/images/blog/image.svg
---

Post will appear on blog page and in RSS feed

Custom Styling

Create _includes/custom-head.html:

<style>
  /* Your custom CSS */
  .my-custom-class {
    /* styles */
  }
</style>

This file is automatically included by the theme’s head.html.

Excalidraw Diagrams

To add an Excalidraw diagram:

Create diagram file in assets/excalidraw/ (e.g., my-diagram.excalidraw)
Reference it in markdown using the include: ```liquid

Loading diagram...

3. The theme's JavaScript will render it automatically
4. Add an edit link (optional):
   ```liquid
   <div class="text-sm text-gray-500 mt-2 mb-6 text-center">
     <a href="/analytiq-pages-starter/excalidraw-edit?file=/analytiq-pages-starter/assets/excalidraw/my-diagram.excalidraw" 
        class="text-gray-500 hover:text-gray-700 no-underline" 
        target="_blank">
       Edit diagram
     </a>
   </div>

Troubleshooting

Theme Not Loading

Check Gemfile has correct theme reference with tag v0.1.8
Run bundle install to download theme
Verify _config.yml has theme: analytiq-pages-theme
Check GitHub repository access (theme is private/public)

Styles Not Applying

Clear Jekyll cache: bundle exec jekyll clean
Check for syntax errors in overridden files
Verify Tailwind CDN is loading in browser dev tools
Ensure no conflicting CSS in custom includes

Build Failures

Check Jekyll version compatibility (via github-pages gem)
Ensure all plugins are listed in Gemfile
Review build logs for specific error messages
Verify Ruby version matches workflow (3.2)

GitHub Pages Deployment Issues

Check GitHub Actions workflow runs successfully
Verify repository has Pages enabled with GitHub Actions source
Check workflow permissions (contents: read, pages: write)
Review workflow logs for build errors

Resources

Next Steps:

Explore the Getting Started guide
Learn about customization options
Check out the API Reference

Overview

Component Architecture

Site Structure (Starter)

Theme Layer (Analytiq Pages Theme)

How It Works

1. Theme Inheritance

2. Override Mechanism

3. Content Rendering Flow

Key Features

Responsive Design

Documentation System

Blog System

Plugins

Configuration

Site Configuration (_config.yml)

Theme Customization

Deployment Architecture

GitHub Pages Deployment

Build Process

GitHub Actions Workflow

File Organization

Actual Structure

Content Organization

Best Practices

Content Organization

Theme Customization

Performance

Extending the Starter

Adding a New Page

Adding a New Documentation Section

Adding a Blog Post

Custom Styling

Excalidraw Diagrams

Troubleshooting

Theme Not Loading

Styles Not Applying

Build Failures

GitHub Pages Deployment Issues

Resources

Site Configuration (`_config.yml`)