AMP Affiliately Jekyll Theme (chriskyfung/amp-affiliately-jekyll-theme)

AMP Affiliately Jekyll Theme

https://github.com/chriskyfung/amp-affiliately-jekyll-theme
Admin
This project offers an AMP-ready Jekyll theme for blogs and websites, featuring responsive design,...

Tokens:60,579
Snippets:529
Trust Score:8.8
Update:1 month ago
Show doc for...
Context Summary (auto-generated)
Raw
# AMP Affiliately Jekyll Theme

AMP Affiliately is an AMP-ready Jekyll theme designed for creating fast, mobile-optimized blogs and websites. Built on top of Google's Accelerated Mobile Pages (AMP) framework, this theme provides a complete solution for content publishers who need high-performance pages with built-in support for Google Analytics 4, Google AdSense, Disqus comments, cookie consent management (including iubenda integration), and responsive design with customizable sidebars and navigation.

The theme offers extensive customization through Jekyll's configuration system and front matter variables, allowing control over layouts, featured images, sidebar widgets, SEO metadata, and CSS styling. It includes a modern build pipeline using Gulp.js for AMP optimization, HTML minification, and SCSS compilation. Key features include syntax highlighting for code blocks, YouTube video embeds with VideoObject schema markup, lightbox image galleries, WebP image format support, and multiple author profiles.

## Installation

Clone the repository and install dependencies using npm, which will also handle Ruby gem installation via Bundler.

```bash
# Clone the repository
git clone https://github.com/chriskyfung/amp-affiliately-jekyll-theme.git
cd amp-affiliately-jekyll-theme

# Install Node.js and Ruby dependencies
npm install

# Start development server with live reload
npm run serve

# Create production build
npm run build

# Run AMP validation tests
npm run test
```

## Site Configuration (_config.yml)

The main configuration file controls site-wide settings including metadata, navigation, analytics, advertising, and third-party integrations.

```yaml
# Site metadata
name: "My AMP Blog"
title: "My AMP Blog"
description: "An AMP-ready Jekyll blog"
url: https://example.com
baseurl: '/blog'
favicon: 'assets/images/favicon.png'
logo: 'assets/images/logo.svg'
permalink: /:year/:month/:day/:title
paginate: 6
timezone: 'America/New_York'

# GitHub repository for metadata widget
repository: username/repo-name

# Navigation configuration
nav:
  buttons:
    gh_sponsors: true
  local:
    items:
      - name: Features
        url: category/feature/
      - name: Docs
        url: category/doc/
    menu: true

# Footer columns configuration
footer:
  col1:
    title: Features
    items:
      - name: Responsive Design
        url: responsive-web-design/
      - name: Media
        url: media/
  col2:
    title: Docs
    items:
      - name: Config Guide
        url: config-guide/

# Sidebar widgets
sidebar:
  featured: true
  recent_posts: true

# Google Analytics 4
ga4: 'G-XXXXXXXXXX'

# Google AdSense
adsense:
  client_id: 'ca-pub-XXXXXXXXXXXXXXXX'
  auto_ads: true
  ad_slot:
    sidebar: 1234567890

# Disqus comments
amp_disqus:
  shortname: 'your-shortname'
  url: 'https://your-disqus-amp-proxy.com/'
  height: 580

# Google Custom Search Engine
cse_id: 'your-cse-id'

# Cookie consent (built-in or iubenda)
consent: true
iubenda:
  siteId: 1234567
  cookiePolicyId: 12345678
  remote_consent_url: https://your-consent-proxy.workers.dev/

# Content post-processing
target_blank: false
anchor_link: true
```

## Post Front Matter

Posts use front matter to define metadata, layout options, featured images, custom CSS, and SEO settings.

```yaml
---
layout: post
title: My Blog Post Title
date: 2024-01-15 12:00 +0000
last_modified_at: 2024-01-20 10:30 +0000
author: chris
categories:
  - tutorial
  - feature
tags:
  - jekyll
  - amp
  - web-development
permalink: /my-custom-url/
excerpt: A brief description for search engines and post cards.

# Featured image configuration
image:
  path: /assets/images/featured-image.png
  width: 1280
  height: 720
  hide: false
  class: shadow-none
  fit: center

# Pin to featured posts widget
featured: true

# Sidebar position: left, right, or none
sidebar: right

# Enable AMP components
amp:
  youtube: true
  gist: true

# Include optional CSS
css:
  syntax: true
  badge: true
  alert: true
  custom: >-
    table { font-size: .95rem; }
    th { background-color: #f8f9fa; }

# Custom HTML head content
custom_head: >-
  <script async custom-element="amp-accordion" src="https://cdn.ampproject.org/v0/amp-accordion-0.1.js"></script>

# SEO settings
canonical_url: https://example.com/canonical-page/
description: Custom meta description for this page.

# URL redirects
redirect_from:
  - /old-url/
  - /another-old-url/

# Sitemap exclusion
sitemap: false

# Hide consent UI on this page
consent_ui: false

# Download buttons in sidebar
download:
  files:
    - url: /downloads/file1.pdf
      name: Documentation PDF
    - url: /downloads/source.zip
      name: Source Code
---
```

## Picture Include (AMP Images with WebP Support)

The `picture.html` include renders AMP-compliant images with automatic WebP format serving and optional lightbox functionality.

```liquid
{% comment %} Basic image with default settings {% endcomment %}
{% include picture.html img="my-photo.jpg" height="400" width="800" %}

{% comment %} Image with caption and alt text {% endcomment %}
{% include picture.html
  img="screenshot.png"
  height="600"
  width="1200"
  alt="Application screenshot showing the dashboard"
  caption="Figure 1: Main dashboard interface"
%}

{% comment %} Image from assets folder with custom class {% endcomment %}
{% include picture.html
  img="logo.png"
  source="assets"
  height="200"
  width="400"
  class="img-fluid shadow-none"
%}

{% comment %} External image URL {% endcomment %}
{% include picture.html
  img="https://example.com/image.jpg"
  source="raw"
  height="300"
  width="600"
  lightbox=false
%}

{% comment %} Image with link wrapper {% endcomment %}
{% include picture.html
  img="product.jpg"
  height="400"
  width="600"
  link="https://example.com/product"
  caption="Click to view product details"
%}

{% comment %} SVG image (no WebP conversion) {% endcomment %}
{% include picture.html
  img="diagram.svg"
  height="500"
  width="800"
  layout="responsive"
%}
```

## YouTube Video Embeds

The `youtube.html` include embeds YouTube videos using the AMP YouTube component with VideoObject schema markup for SEO.

```liquid
{% comment %} First, enable YouTube in front matter {% endcomment %}
---
amp:
  youtube: true
---

{% comment %} Basic video embed {% endcomment %}
{% include youtube.html id="dQw4w9WgXcQ" %}

{% comment %} Video with full SEO metadata {% endcomment %}
{% include youtube.html
  id="dQw4w9WgXcQ"
  title="Rick Astley - Never Gonna Give You Up"
  description="The official video for Rick Astley's hit song from 1987."
  upload_date="2009-10-25T00:00:00Z"
  thumb_quality="maxres"
%}

{% comment %} Embed a playlist (requires first video ID and playlist ID) {% endcomment %}
{% include youtube.html
  id="PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf"
  playlist="PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf"
  title="My Playlist Collection"
%}

{% comment %} Video thumbnail link (for sidebars/lists) {% endcomment %}
{% include youtube-thumb.html
  id="dQw4w9WgXcQ"
  title="Watch this video"
%}
```

## Alert Component

The `alert.html` include creates Bootstrap 4-style alert boxes with different types for info, success, warning, and danger messages.

```liquid
{% comment %} Info alert {% endcomment %}
{% capture info_content %}
**Note:** This feature requires Jekyll 4.0 or higher.
{% endcapture %}
{% include alert.html type="info" content=info_content %}

{% comment %} Success alert with title {% endcomment %}
{% capture success_content %}
Your configuration has been saved successfully.
{% endcapture %}
{% include alert.html type="success" title="Success!" content=success_content %}

{% comment %} Warning alert {% endcomment %}
{% capture warning_content %}
This method is deprecated and will be removed in v4.0.
{% endcapture %}
{% include alert.html type="warning" content=warning_content %}

{% comment %} Danger alert {% endcomment %}
{% capture danger_content %}
**Critical:** Do not expose your API keys in client-side code.
{% endcapture %}
{% include alert.html type="danger" title="Security Warning" content=danger_content %}

{% comment %} Default primary alert {% endcomment %}
{% include alert.html content="This is a default primary alert message." %}
```

## Callout Component

The `callout.html` include creates highlighted boxes for tips, notes, and important information with customizable colors.

```liquid
{% comment %} Default yellow callout {% endcomment %}
{% capture tip_content %}
**Pro Tip:** Use keyboard shortcut `Ctrl+S` to save your work quickly.
{% endcapture %}
{% include callout.html content=tip_content %}

{% comment %} Callout with title {% endcomment %}
{% capture note_content %}
Remember to backup your `_config.yml` before making changes.
{% endcapture %}
{% include callout.html title="Important Note" content=note_content %}

{% comment %} Typed callouts (info, success, warning, danger) {% endcomment %}
{% capture info_text %}
This section covers advanced configuration options.
{% endcapture %}
{% include callout.html type="info" content=info_text %}

{% capture warning_text %}
Modifying these files may break your site build.
{% endcapture %}
{% include callout.html type="warning" title="Caution" content=warning_text %}

{% comment %} Custom color callout {% endcomment %}
{% capture custom_content %}
This callout uses a custom lavender background color.
{% endcapture %}
{% include callout.html color="#e6e6fa" content=custom_content %}
```

## Syntax Highlighting for Code Blocks

Enable syntax highlighting by setting the front matter flag and using fenced code blocks with language identifiers.

```yaml
---
css:
  syntax: true
---
```

````markdown
```ruby
# Ruby example with syntax highlighting
def greet(name)
  puts "Hello, #{name}!"
end

greet("World")
```

```javascript
// JavaScript example
const fetchData = async (url) => {
  try {
    const response = await fetch(url);
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Fetch error:', error);
  }
};
```

```yaml
# YAML configuration example
site:
  title: My Blog
  author: John Doe
  features:
    - responsive
    - amp-ready
    - seo-optimized
```
````

## Available Layouts

The theme provides multiple layouts for different page types including posts, pages, archives, and lists.

```yaml
# Post layout with sidebar (default right)
---
layout: post
title: My Blog Post
sidebar: right
---

# Page layout without sidebar
---
layout: page
title: About Us
sidebar: none
---

# Page with right sidebar
---
layout: page-right-sidebar
title: Services
---

# Post with left sidebar
---
layout: post-left-sidebar
title: Tutorial Post
---

# Blog pagination page (create at /blog/index.html)
---
layout: blog-pagination
---

# Category list page (create at /category/index.html)
---
layout: category-list
title: All Categories
---

# Tag list page (create at /tag/index.html)
---
layout: tag-list
title: All Tags
---

# Archive layout for category/tag pages (auto-generated)
---
layout: archive
---
```

## Author Configuration

Define multiple authors in `_data/authors.yml` and reference them in posts using the author key.

```yaml
# _data/authors.yml
chris:
  name: Chris KY Fung
  display_name: Chris F.
  gravatar: abd876486b2caa54b43bf64a5a86f620
  email: chris@example.com
  web: https://chriskyfung.github.io
  facebook: https://www.facebook.com/chriskyfung/
  description: "Author of this blog, M.Phil."

john:
  name: John Smith
  display_name: John
  gravatar:
  email: john@example.com
  web: https://johnsmith.com
  facebook: https://www.facebook.com/johnsmith
  description: "Technical writer and developer advocate."

jane:
  name: Jane Doe
  display_name: Jane D.
  gravatar:
  email: jane@example.com
  web: https://janedoe.dev
  description: "Full-stack developer and UX specialist."
```

```yaml
# Reference in post front matter
---
layout: post
title: Getting Started with AMP
author: chris
---
```

## Build and Development Scripts

The theme includes npm scripts for development, building, and testing the site.

```bash
# Development server with live reload
npm run serve

# Production build (SCSS compile + Jekyll build + AMP optimize + minify)
npm run build

# Development build (without production optimizations)
npm run build:dev

# Run AMP validation on generated site
npm run test

# Full AMP validation without ignoring any files
npm run test:dev

# Compile and optimize SCSS/CSS only
npm run css:build

# Watch SCSS/CSS files for changes
npm run watch:all

# Run Jekyll serve directly
bundle exec jekyll serve --livereload

# Build Jekyll site only
bundle exec jekyll build
```

## Summary

AMP Affiliately Jekyll Theme is ideal for bloggers, content creators, and project documentation sites that require fast-loading, mobile-first pages with strong SEO capabilities. The theme excels in scenarios requiring Google AMP compliance, integrated advertising, analytics tracking, and cookie consent management for GDPR compliance. Its modular architecture with customizable sidebars, footer columns, and navigation makes it suitable for both simple blogs and complex multi-author publications.

Integration patterns follow standard Jekyll conventions with Liquid templating for includes and layouts, YAML configuration for site-wide settings, and front matter for per-page customization. The Gulp-based build pipeline handles AMP optimization automatically, making it straightforward to deploy to GitHub Pages via the included GitHub Actions workflow. Developers can extend the theme by adding custom AMP components through the `custom_head` front matter variable, creating custom sidebar widgets, or modifying the SCSS source files in the `_sass` directory.