Core API Reference

airheads.build_social_head(title, description, url, image, *extra_children, keywords=None, image_alt=None, image_width=1200, image_height=630, site_name=None, twitter_site=None, twitter_creator=None, author=None, canonical_url=None, favicon_ico='/favicon.ico', theme_color=None, og_type='website', twitter_card='summary_large_image', locale='en_US', robots='index, follow', viewport='width=device-width, initial-scale=1.0', charset='utf-8', **kwargs)

Build a complete Head tag with all social media, SEO, and standard elements.

This is a convenience function that combines build_seo_meta(), build_open_graph(), build_twitter_card(), and build_favicon_links() into a single Head tag.

Parameters:

Name	Type	Description	Default
title	str	Page title	required
description	str	Page description	required
url	str	Canonical URL	required
image	str	Social sharing image URL	required
*extra_children	BaseTag	Additional tags to include in the head	()
keywords	Sequence[str] | None	SEO keywords	None
image_alt	str | None	Alt text for social image	None
image_width	int | None	Image width in pixels (default: 1200)	1200
image_height	int | None	Image height in pixels (default: 630)	630
site_name	str | None	Site name for Open Graph	None
twitter_site	str | None	Twitter handle for the site (e.g., "@mysite")	None
twitter_creator	str | None	Twitter handle for the creator (e.g., "@author")	None
author	str | None	Page author	None
canonical_url	str | None	Canonical URL (defaults to url if not provided)	None
favicon_ico	str | None	Path to favicon (default: "/favicon.ico")	'/favicon.ico'
theme_color	str | None	Browser theme color	None
og_type	str	Open Graph type (default: "website")	'website'
twitter_card	str	Twitter card type (default: "summary_large_image")	'summary_large_image'
locale	str	Content locale (default: "en_US")	'en_US'
robots	str	Robots meta tag value (default: "index, follow")	'index, follow'
viewport	str	Viewport settings	'width=device-width, initial-scale=1.0'
charset	str	Character encoding (default: "utf-8")	'utf-8'
**kwargs	str	Additional attributes for the Head tag	{}

Returns:

Type	Description
Head	Complete Head tag with all social and SEO elements

Example

from air import Html, Body, H1 from airheads import build_social_head

html = Html( ... build_social_head( ... title="My Awesome Site", ... description="Welcome to my site", ... url="https://example.com", ... image="https://example.com/og-image.jpg", ... site_name="Example.com", ... twitter_site="@example", ... keywords=["python", "web", "framework"], ... ), ... Body( ... H1("Welcome to My Site") ... ) ... )

airheads.build_seo_meta(description, keywords=None, canonical_url=None, robots='index, follow', author=None, viewport='width=device-width, initial-scale=1.0', charset='utf-8', theme_color=None)

Build standard SEO meta tags.

Parameters:

Name	Type	Description	Default
description	str	Page description for search results	required
keywords	Sequence[str] | None	List of keywords for the page	None
canonical_url	str | None	Canonical URL to avoid duplicate content issues	None
robots	str	Robots meta tag value (default: "index, follow")	'index, follow'
author	str | None	Page author name	None
viewport	str	Viewport settings for responsive design	'width=device-width, initial-scale=1.0'
charset	str	Character encoding (default: "utf-8")	'utf-8'
theme_color	str | None	Theme color for browser UI	None

Returns:

Type	Description
list[BaseTag]	List of Meta and Link tags for SEO

Example

from airheads import build_seo_meta tags = build_seo_meta( ... description="This is a great page", ... keywords=["python", "web", "framework"], ... canonical_url="https://example.com/page" ... )

airheads.build_open_graph(title, description, url, image, image_alt=None, image_width=None, image_height=None, type='website', site_name=None, locale='en_US', article_author=None, article_published_time=None, article_modified_time=None, article_section=None, article_tags=None)

Build Open Graph meta tags for Facebook, LinkedIn, and other social platforms.

Parameters:

Name	Type	Description	Default
title	str	Content title	required
description	str	Content description	required
url	str	Canonical URL of the page	required
image	str	URL to image for social sharing	required
image_alt	str | None	Alt text for the image	None
image_width	int | None	Image width in pixels (recommended: 1200)	None
image_height	int | None	Image height in pixels (recommended: 630)	None
type	str	Content type (e.g., "website", "article", "video.movie")	'website'
site_name	str | None	Name of the overall site	None
locale	str	Locale/language (default: "en_US")	'en_US'
article_author	str | None	Article author (for type="article")	None
article_published_time	str | None	ISO 8601 datetime (for type="article")	None
article_modified_time	str | None	ISO 8601 datetime (for type="article")	None
article_section	str | None	Article section/category (for type="article")	None
article_tags	Sequence[str] | None	List of article tags (for type="article")	None

Returns:

Type	Description
list[BaseTag]	List of Meta tags with Open Graph properties

Example

from airheads import build_open_graph tags = build_open_graph( ... title="My Article", ... description="An interesting article", ... url="https://example.com/article", ... image="https://example.com/image.jpg", ... type="article", ... site_name="My Blog" ... )

airheads.build_twitter_card(card_type='summary_large_image', title=None, description=None, image=None, image_alt=None, site=None, creator=None)

Build Twitter Card meta tags for Twitter/X social sharing.

Parameters:

Name	Type	Description	Default
card_type	str	Type of card ("summary", "summary_large_image", "app", "player")	'summary_large_image'
title	str | None	Title for the card (falls back to og:title if not specified)	None
description	str | None	Description for the card (falls back to og:description if not specified)	None
image	str | None	Image URL for the card (falls back to og:image if not specified)	None
image_alt	str | None	Alt text for the image	None
site	str | None	Twitter handle for the website (e.g., "@mysite")	None
creator	str | None	Twitter handle for content creator (e.g., "@author")	None

Returns:

Type	Description
list[BaseTag]	List of Meta tags for Twitter Cards

Example

from airheads import build_twitter_card tags = build_twitter_card( ... card_type="summary_large_image", ... title="My Article", ... description="An interesting article", ... image="https://example.com/image.jpg", ... site="@mysite", ... creator="@author" ... )

airheads.build_favicon_links(favicon_ico='/favicon.ico', favicon_svg=None, apple_touch_icon=None, icon_192=None, icon_512=None, manifest='/manifest.json')

Build favicon and icon link tags for various platforms and sizes.

Parameters:

Name	Type	Description	Default
favicon_ico	str | None	Path to .ico favicon (default: "/favicon.ico")	'/favicon.ico'
favicon_svg	str | None	Path to .svg favicon (modern browsers)	None
apple_touch_icon	str | None	Path to Apple touch icon (180x180 recommended)	None
icon_192	str | None	Path to 192x192 PNG icon (Android)	None
icon_512	str | None	Path to 512x512 PNG icon (Android)	None
manifest	str | None	Path to web app manifest (default: "/manifest.json")	'/manifest.json'

Returns:

Type	Description
list[BaseTag]	List of Link tags for favicons and icons

Example

from airheads import build_favicon_links tags = build_favicon_links( ... favicon_ico="/static/favicon.ico", ... favicon_svg="/static/favicon.svg", ... apple_touch_icon="/static/apple-touch-icon.png" ... )

airheads.build_json_ld(json_ld_script)

Build a JSON-LD structured data script tag.

Parameters:

Name	Type	Description	Default
json_ld_script	str	JSON-LD structured data as a string	required

Returns:

Type	Description
Script	Script tag containing JSON-LD data

Example

import json from airheads import build_json_ld data = { ... "@context": "https://schema.org", ... "@type": "Article", ... "headline": "My Article", ... "author": {"@type": "Person", "name": "John Doe"} ... } script = build_json_ld(json.dumps(data))