API Reference

This reference documents the configuration and template APIs available in the Analytiq Pages Starter. Since this is a static site generator, there are no REST APIs—instead, this documents the configuration options, front matter fields, Liquid template variables, and includes available for customizing your site.

Site Configuration API (`_config.yml`)

The _config.yml file configures your entire site. All settings are available as site.* variables in templates.

Site Metadata

Field	Type	Required	Description
`title`	string	Yes	Site title displayed in header and meta tags
`author.name`	string	No	Author name for blog posts
`author.email`	string	No	Author email address
`description`	string	No	Site description for SEO
`baseurl`	string	No	Base URL for site (empty for root)
`url`	string	No	Full site URL (defaults to GitHub Pages URL)
`repository`	string	No	GitHub repository (format: `org/repo`)

Example:

title: Your Company Name
author:
  name: Your Name
  email: "hello@yourcompany.com"
description: Your company description
repository: yourorg/yourrepo

Theme Configuration

Field	Type	Required	Description
`theme`	string	Yes	Theme name (must be `analytiq-pages-theme`)

Example:

theme: analytiq-pages-theme

Header Navigation (`header_pages`)

Configure the main navigation menu:

Field	Type	Required	Description
`title`	string	Yes	Menu item label
`url`	string	Yes	URL or `"#"` for dropdown
`children`	array	No	Submenu items
`button_style`	string	No	`"solid"` to render as button

Example:

header_pages:
  - title: "Products"
    url: "#"
    children:
      - title: "Overview"
        url: "/products"
      - title: "Features"
        url: "/features"
  - title: "Get Started"
    url: "/contact"
    button_style: "solid"

Footer Sitemap (`site_map`)

Configure footer navigation:

Field	Type	Required	Description
`title`	string	Yes	Section title
`links`	array	Yes	Array of link objects with `title` and `url`

Example:

site_map:
  - title: "Products"
    links:
      - title: "Overview"
        url: "/products"

Collections API

Configure Jekyll collections (like blog posts):

Field	Type	Required	Description
`output`	boolean	No	Generate HTML files (default: `false`)
`permalink`	string	No	URL pattern for collection items

Example:

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

Pagination API

Configure blog pagination using jekyll-paginate-v2:

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable pagination
`per_page`	integer	Yes	Posts per page
`permalink`	string	No	URL pattern (default: `/page/:num/`)
`sort_field`	string	No	Field to sort by (default: `date`)
`sort_reverse`	boolean	No	Reverse sort order (default: `true`)
`trail.before`	integer	No	Pages before current in trail
`trail.after`	integer	No	Pages after current in trail

Example:

pagination:
  enabled: true
  per_page: 5
  permalink: '/page/:num/'
  sort_field: 'date'
  sort_reverse: true
  trail:
    before: 2
    after: 2

Plugins API

List enabled Jekyll plugins:

Plugin	Description
`jekyll-feed`	Generates RSS feed for blog posts
`jekyll-seo-tag`	Adds SEO meta tags to pages
`jekyll-pdf-embed`	Allows embedding PDF files
`jekyll-paginate-v2`	Advanced pagination for blog

Example:

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

Front Matter API

Front matter defines page metadata and is available as page.* variables in templates.

Common Front Matter Fields

Field	Type	Required	Description
`layout`	string	Yes	Layout template to use
`title`	string	Yes	Page title
`permalink`	string	No	Custom URL path
`description`	string	No	Page description for SEO
`image`	string	No	Featured image URL

Page Layout Front Matter

For standard pages (layout: page):

---
layout: page
title: Services
permalink: /services/
description: Our service offerings
---

Post Layout Front Matter

For blog posts (layout: post):

Field	Type	Required	Description
`date`	datetime	Yes	Publication date
`categories`	array/string	No	Space-separated categories
`author`	string	No	Author name
`image`	string	No	Post preview image

Example:

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

Docs Layout Front Matter

For documentation pages (layout: docs):

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

Liquid Template API

Liquid is the templating language used by Jekyll. Variables and filters are available in all templates.

Site Variables

Access site configuration:

Variable	Description
`site.title`	Site title from `_config.yml`
`site.description`	Site description
`site.author`	Author object
`site.header_pages`	Header navigation array
`site.posts`	All blog posts collection

Example:

<h1>{{ site.title }}</h1>
<p>{{ site.description }}</p>

Page Variables

Access current page data:

Variable	Description
`page.title`	Page title from front matter
`page.url`	Page URL path
`page.date`	Page/post date
`page.categories`	Post categories array
`page.content`	Page content (markdown rendered)

Example:

<h1>{{ page.title }}</h1>
<div>{{ page.content }}</div>

Common Liquid Filters

Filter	Description	Example
`relative_url`	Convert to relative URL	`{{ '/about' \\| relative_url }}`
`date`	Format date	`{{ page.date \\| date: "%B %d, %Y" }}`
`markdownify`	Convert markdown to HTML	`{{ content \\| markdownify }}`
`strip_html`	Remove HTML tags	`{{ content \\| strip_html }}`
`truncate`	Limit text length	`{{ content \\| truncate: 200 }}`
`slugify`	Convert to URL slug	`{{ title \\| slugify }}`
`where`	Filter array	`{{ site.posts \\| where: "category", "engineering" }}`
`sort`	Sort array	`{{ site.posts \\| sort: "date" }}`
`first`	Get first item	`{{ site.posts \\| first }}`
`last`	Get last item	`{{ site.posts \\| last }}`

Pagination Variables

Available on paginated pages:

Variable	Description
`paginator.page`	Current page number
`paginator.per_page`	Posts per page
`paginator.posts`	Posts for current page
`paginator.total_posts`	Total number of posts
`paginator.total_pages`	Total number of pages
`paginator.previous_page`	Previous page number (or `nil`)
`paginator.next_page`	Next page number (or `nil`)
`paginator.previous_page_path`	Path to previous page
`paginator.next_page_path`	Path to next page

Example:

{% for post in paginator.posts %}
  <article>
    <h2>{{ post.title }}</h2>
    {{ post.content }}
  </article>
{% endfor %}

{% if paginator.next_page %}
  <a href="{{ paginator.next_page_path }}">Next Page</a>
{% endif %}

Include API

Theme includes are reusable components. Override them by creating files in _includes/.

Excalidraw Includes

`excalidraw-static.html`

Render Excalidraw diagram as static SVG.

Parameters:

Parameter	Type	Required	Description
`file`	string	Yes	Path to `.excalidraw` file

Example:

<div
  class="excalidraw-static"
  data-excalidraw="/analytiq-pages-starter/assets/excalidraw/diagram.excalidraw"
  style="margin: 2rem 0;">
  <div class="loading" style="padding: 2rem; text-align: center; color: #666;">Loading diagram...</div>
</div>


  <script type="module" src="/analytiq-pages-starter/assets/js/excalidraw/render-excalidraw.js" defer></script>
  

`excalidraw.html`

Smart Excalidraw embed with multiple rendering modes.

Parameters:

Parameter	Type	Required	Description
`file`	string	Yes	Path to `.excalidraw` file
`mode`	string	No	`"static"` (default), `"interactive"`, or `"link"`
`width`	string	No	Width for interactive mode (default: `"100%"`)
`height`	string	No	Height for interactive mode (default: `"600px"`)

Example:

  <!-- Static SVG -->
  

<div
  class="excalidraw-static"
  data-excalidraw="/analytiq-pages-starter/assets/excalidraw/diagram.excalidraw"
  style="margin: 2rem 0;">
  <div class="loading" style="padding: 2rem; text-align: center; color: #666;">Loading diagram...</div>
</div>


  <script type="module" src="/analytiq-pages-starter/assets/js/excalidraw/render-excalidraw.js" defer></script>
  

Custom Includes

Create custom includes in _includes/:

Example (_includes/custom-head.html):

<style>
  /* Custom CSS */
</style>

Automatically included by theme’s head.html.

Layout API

Available layouts and their usage:

`default`

Standard page layout with header and footer.

Usage:

---
layout: default
title: Home
---

`page`

Content-focused page layout.

Usage:

---
layout: page
title: About
permalink: /about/
---

`post`

Blog post layout with date, author, and categories.

Usage:

---
layout: post
title: "Post Title"
date: 2025-11-29 10:00:00 -0400
categories: engineering
---

`docs`

Documentation layout with sidebar navigation.

Usage:

---
layout: docs
title: Getting Started
permalink: /docs/getting-started/
---

`excalidraw-editor`

Excalidraw diagram editor layout.

Usage:

---
layout: excalidraw-editor
permalink: /excalidraw-edit
---

Collections API

Posts Collection

The posts collection contains blog posts.

Access in templates:

{% for post in site.posts %}
  <h2>{{ post.title }}</h2>
{% endfor %}

Post properties:

post.title - Post title
post.date - Publication date
post.categories - Categories array
post.author - Author name
post.image - Preview image URL
post.url - Post URL
post.content - Post content
post.excerpt - Post excerpt

Pagination API

Pagination is configured in _config.yml and available via paginator object.

Access paginated posts:

{% for post in paginator.posts %}
  <!-- Post content -->
{% endfor %}

Pagination controls:

{% if paginator.previous_page %}
  <a href="{{ paginator.previous_page_path }}">Previous</a>
{% endif %}

Page {{ paginator.page }} of {{ paginator.total_pages }}

{% if paginator.next_page %}
  <a href="{{ paginator.next_page_path }}">Next</a>
{% endif %}

Error Handling

Configuration Errors

If _config.yml has syntax errors:

Jekyll build will fail
Check YAML syntax (indentation, quotes)
Validate with online YAML validator

Template Errors

If Liquid templates have errors:

Jekyll will show error messages during build
Check for unclosed tags: {% if %}...{% endif %}
Verify variable names match front matter

Common Issues

Issue	Solution
Variable not found	Check spelling and ensure it exists in front matter or `_config.yml`
Filter error	Verify filter syntax and input type
Include not found	Check file exists in `_includes/` or theme
Layout not found	Verify layout exists in theme or create override

API Reference

Site Configuration API (`_config.yml`)

Site Metadata

Theme Configuration

Navigation API

Header Navigation (`header_pages`)

Footer Sitemap (`site_map`)

Collections API

Plugins API

Front Matter API

Common Front Matter Fields

Page Layout Front Matter

Post Layout Front Matter

Docs Layout Front Matter

Liquid Template API

Site Variables

Page Variables

Common Liquid Filters

Include API

Excalidraw Includes

`excalidraw-static.html`

`excalidraw.html`

Custom Includes

Layout API

`default`

`page`

`post`

`docs`

`excalidraw-editor`

Collections API

Posts Collection

Error Handling

Configuration Errors

Template Errors

Common Issues

Best Practices

Configuration

Front Matter

Templates

Additional Resources

Site Configuration API (_config.yml)

Site Metadata

Theme Configuration

Navigation API

Header Navigation (header_pages)

Footer Sitemap (site_map)

Collections API

Pagination API

Plugins API

Front Matter API

Common Front Matter Fields

Page Layout Front Matter

Post Layout Front Matter

Docs Layout Front Matter

Liquid Template API

Site Variables

Page Variables

Common Liquid Filters

Pagination Variables

Include API

Excalidraw Includes

excalidraw-static.html

excalidraw.html

Custom Includes

Layout API

default

page

post

docs

excalidraw-editor

Collections API

Posts Collection

Pagination API

Error Handling

Configuration Errors

Template Errors

Common Issues

Best Practices

Configuration

Front Matter

Templates

Additional Resources

Site Configuration API (`_config.yml`)

Header Navigation (`header_pages`)

Footer Sitemap (`site_map`)

`excalidraw-static.html`

`excalidraw.html`

`default`

`page`

`post`

`docs`

`excalidraw-editor`