CLAUDE.md

Project context for AI assistants working on the SpecLynx website.

Project Overview

Jekyll static site for SpecLynx — an API tooling company. Hosted on GitHub Pages at https://speclynx.com/.

Three products:

Tech Stack

Jekyll Plugins

Build & Serve

bundle exec jekyll serve        # Dev server (localhost:4000)
bundle exec jekyll build        # Build to _site/

File Structure

_config.yml                      # Site config (title, url, baseurl, plugins)
_layouts/
  base.html                      # HTML skeleton: head, nav, content, footer, org schema
  default.html                   # Wraps content in container (inherits base)
_includes/
  head.html                      # <head> with seo tag, meta, CDN scripts
  nav.html                       # Responsive navbar with dropdowns
  footer.html                    # Footer with links and social icons
  schema-organization.html       # Organization JSON-LD (included sitewide)
  apidom-sidebar.html            # Shared sidebar for ApiDOM pages (active state via page.url)
pages/
  homepage.html                  # Landing page (permalink: /)
  openapi-toolkit.html           # Product page with sidebar nav
  language-service.html          # Product page with sidebar nav
  apidom/overview.html           # ApiDOM overview (permalink: /apidom/)
  apidom/installation.html       # ApiDOM installation guide (permalink: /apidom/installation/)
  apidom/parsing.html            # ApiDOM parsing guide (permalink: /apidom/parsing/)
  about.html                     # Team page
  pricing.html                   # Free + Enterprise tiers
  privacy.html, terms.html       # Legal pages
assets/
  css/main.css                   # Custom CSS + CSS variables
  js/main.js                     # Mobile menu, lightbox, tooltips, heading anchors
  images/                        # Logos, diagrams, screenshots
robots.txt                       # Sitemap directive (uses Jekyll variables)
llms.txt                         # LLM crawler discovery file

CSS Conventions

Inline Links in Body Text

Use class="text-primary-light underline hover:no-underline" for links inside paragraphs. This ensures links are distinguishable by more than color alone (Lighthouse accessibility requirement).

Heading Anchors

JavaScript in main.js auto-generates # anchor links on headings with IDs and on first headings inside sections with IDs. Uses :scope > selector to avoid duplicates from nested sections.

All <h3> elements on product pages have descriptive IDs matching their text (e.g., id="parsing-an-openapi-document").

scroll-margin-top: 80px on [id] elements prevents anchors from hiding under the sticky header.

Quality Checks

W3C HTML Validation

All pages pass with 0 errors via https://validator.w3.org/nu/ (POST rendered HTML).

Run with:

curl -s -H "Content-Type: text/html; charset=utf-8" \
  --data-binary @_site/path/to/index.html \
  "https://validator.w3.org/nu/?out=json" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); errors=[m for m in d.get('messages',[]) if m['type']=='error']; print(f'{len(errors)} errors'); [print(f\"  L{m.get('lastLine','?')}: {m['message']}\") for m in errors]"

Note: jekyll-seo-tag generates <meta ... /> with trailing slashes (XHTML style). These show as validator infos, not errors. Cannot be fixed on our side — it’s the plugin’s output.

Chrome Lighthouse

All pages score 100 on Accessibility, SEO, and Best Practices.

Run with (requires bundle exec jekyll serve running on localhost:4000):

npx lighthouse http://localhost:4000/path/ \
  --chrome-flags="--headless --no-sandbox" \
  --only-categories=accessibility,best-practices,seo \
  --output=json --quiet 2>/dev/null \
  | python3 -c "import sys,json; d=json.load(sys.stdin); cats=d['categories']; print(f\"Accessibility: {int(cats['accessibility']['score']*100)}\"); print(f\"Best Practices: {int(cats['best-practices']['score']*100)}\"); print(f\"SEO: {int(cats['seo']['score']*100)}\")"

Key accessibility decisions:

Images

AEO (Answer Engine Optimization)

Schema.org JSON-LD Structured Data

FAQ Sections

Each product page has a visible FAQ section at the bottom with matching FAQPage JSON-LD. Keep the visible HTML text and JSON-LD text values in sync when editing.

robots.txt

Uses Jekyll front matter (layout: none) so Liquid variables resolve. Contains Sitemap: directive pointing to https://speclynx.com/sitemap.xml.

llms.txt

Plain-text file at site root describing the company and products for LLM crawlers. Also uses Jekyll variables for URLs.

ApiDOM Documentation Pages

ApiDOM has a multi-page documentation section with a shared sidebar (_includes/apidom-sidebar.html):

Key conventions for ApiDOM content:

Important Notes