easeo 0.2.0

easeo

A deterministic SEO metadata library for content platforms.

Generate canonical URLs, titles, descriptions, robots directives, Open Graph, Twitter Cards, and JSON-LD from content entities. One Rust core with Python, Node.js, and Rust APIs.

What is easeo

easeo is a deterministic SEO metadata library: you call it; it doesn't own your app's routing, rendering, or lifecycle. It takes a content entity, the route it lives at, and a site-wide configuration, and returns a complete SEO payload: canonical URL, title, description, robots directives, Open Graph, Twitter Cards, and JSON-LD.

All logic lives in the Rust core (easeo-core). The Python and Node.js packages wrap the same engine, so the same entity, route, and config produce identical output in every language. The cross-language conformance suite asserts that byte for byte.

The tutorial walks through installation and a first payload. Concepts explains the entity model, fallback chains, URL normalization, and validation rules.

Content Entity
      |
      v
   easeo
      |
      +-- canonical URL
      +-- title & description
      +-- robots directives
      +-- Open Graph
      +-- Twitter Cards
      +-- JSON-LD
      |
      v
 Deterministic Payload

Quick start

Every binding exposes the same call: pass an entity, a route, and a config, and get a payload back. The full tutorial covers configuration, overrides, rendering, and contracts.

Python

pip install easeo

from easeo import SEOConfig, SEOEntity, build_seo_payload

config = SEOConfig(
    canonical_host="example.com",
    public_base_url="https://example.com",
)

entity = SEOEntity(
    entity_type="post",
    title="Hello World",
    excerpt="An example post.",
)

payload = build_seo_payload(entity, "/blog/hello", config)
print(payload.render_html())

JavaScript / TypeScript

npm install @easeo/core

import { buildSeoPayload } from "@easeo/core";

const payload = buildSeoPayload(
  { entityType: "post", title: "Hello World", description: "An example post." },
  "/blog/hello",
  { canonicalHost: "example.com", publicBaseUrl: "https://example.com" }
);

console.log(payload.renderHtml());

Rust

cargo add easeo-core

use easeo_core::{SEOConfig, SEOEntity, EntityType, build_seo_payload};

let config = SEOConfig {
    canonical_host: "example.com".into(),
    public_base_url: "https://example.com".into(),
    ..Default::default()
};

let entity = SEOEntity {
    entity_type: EntityType::Post,
    title: Some("Hello World".into()),
    excerpt: Some("An example post.".into()),
    ..Default::default()
};

let payload = build_seo_payload(&entity, "/blog/hello", &config).unwrap();
assert_eq!(payload.canonical, "https://example.com/blog/hello");

Why easeo

Other SEO libraries do too much (scoring, keyword analysis, content rewriting), while easeo does one thing and does it well: generate deterministic SEO metadata from content entities.

Given the same inputs, easeo always produces the same output. No timestamps, no randomness, no environment reads, no hidden I/O. This makes SEO metadata something you can:

• snapshot test: assert against expected payloads
• hash: generate stable ETags
• cache: safely memoize results
• diff: detect changes across builds
• validate in CI: commit your SEO intent as code with contracts

See Why easeo for the design goals and a comparison with other SEO tooling.

What easeo is not

• Not a framework. Adapters are thin marshalling helpers, not lifecycle owners.
• Not a scoring or keyword analysis tool.
• Not a crawler or site auditor.
• Not a content rewriter or generator.
• Not a runtime service. It is a pure function over its inputs.
• Not a full page renderer. It renders a head snippet, not a document.

Features

• 11 entity types: home, post, page, video, taxonomy, search, product, organization, local_business, faq, other. See the entity model
• URL normalization: HTTPS enforcement, lowercase paths, trailing slash control, duplicate slash collapse, tracking parameter removal. See URL normalization
• JSON-LD schemas: WebSite, WebPage, Article, Product, Organization, LocalBusiness, FAQPage, BreadcrumbList, plus custom schemas via registry. See JSON-LD schemas and custom JSON-LD
• Open Graph: full og:type, title, description, image, locale, audio, video
• Twitter Cards: summary_large_image by default, with image alt, site, creator
• Robots directives: index/noindex, follow/nofollow, max-snippet, max-image-preview, max-video-preview
• SEO contracts: machine-readable SEO intent for CI validation. See the contract reference
• Validation: built-in checks for title length, description, canonical format, OG image, robots directives. See validation
• Hashing: SHA-256 payload hashing and ETag generation
• HTML rendering: complete head snippet with meta tags, OG, Twitter, JSON-LD
• Extension points: config-scoped hooks and schema registries. See hooks

Learn more in the guides and start from a recipe such as a blog post, product page, or search results page.

Packages

Integrations

Per-framework setup guides live in the Integrations docs.

JavaScript / TypeScript

Python

API

Names are shown in Python. JavaScript uses camelCase and Rust uses snake_case. Full signatures live in the Python, JavaScript, and Rust API references.

Documentation

• Tutorial: installation, first payload, rendering, contracts, configuration
• Concepts: determinism, entity and payload models, fallback chains, URL normalization, schemas, validation
• Guides: custom JSON-LD, hooks, contracts in CI, framework recipes
• Reference: Python, JavaScript, and Rust APIs, contracts, errors
• Integrations: per-framework setup
• Recipes: blog post, product page, category page, search results
• Examples: core and framework examples for every binding

LLM-friendly versions: llms.txt and llms-full.txt.

Building

# Rust core
cargo build --workspace --release

# Python bindings
pip install maturin
maturin develop -m crates/easeo-python/Cargo.toml

# Node bindings
npm install -g @napi-rs/cli@^3
cd packages/core
napi build --platform --release --manifest-path ../../crates/easeo-node/Cargo.toml
cp ../../crates/easeo-node/*.node .

Testing

# Rust
cargo test --workspace

# Python
pytest tests/python/

# JavaScript
node --test tests/javascript/*.cjs

# Cross-language conformance
python tests/conformance/test_conformance.py

Next steps

• Follow the tutorial from installation to first payload
• Commit SEO intent with contracts in CI
• Extend structured data with custom schemas
• Read how fields resolve in fallback chains
• Browse examples for every binding and framework

Contributors

• Emiliano Gandini Outeda: creator and maintainer

License

MIT