Describe a page to search engines with JSON-LD, and serialize it for a <script type="application/ld+json">. Every < is escaped, so text in the data can’t close the script element:
ts
import { buildStructuredData, serializeStructuredData } from 'jg-site';const json = serializeStructuredData( buildStructuredData({ breadcrumbs: [ { name: 'Docs', path: '/' }, { name: 'Install', path: '/install/' }, ], canonicalUrl: 'https://docs.example.com/install/', description: 'Install the CLI with npm, pnpm, or Yarn, and check that it runs.', site: { author: { name: 'Ada Lovelace', url: 'https://ada.example.com/' }, language: 'en', name: 'Example Docs', url: 'https://docs.example.com', }, title: 'Install | Example Docs', type: 'webpage', }),);
A page that builds the rest of its structured data itself can add just the breadcrumb. A step without a URL, such as the current page, has no item:
Write an llms.txt in the llmstxt.org format, and an llms-full.txt from the site’s Markdown documents:
ts
import { buildLlmsFullText, buildLlmsText } from 'jg-site';const llmsText = buildLlmsText({ name: 'Example Docs', summary: 'Guides and the API reference for the Example CLI.', sections: [ { heading: 'Guides', links: [ { title: 'Install', url: 'https://docs.example.com/install.md', description: 'Set it up.' }, { title: 'Changelog', url: 'https://docs.example.com/changelog.md' }, ], }, ],});const llmsFullText = buildLlmsFullText({ name: 'Example Docs', summary: 'Guides and the API reference for the Example CLI.', documents: ['# Install\n\nRun `npm install example-cli`.\n'],});
Read and store a visitor’s theme preference. Stored values are untrusted, so anything unknown reads as 'system', and a browser that blocks storage never throws:
ts
import { readThemePreference, resolveThemePreference, writeThemePreference } from 'jg-site';const preference = readThemePreference('example-theme'); // 'system', 'light', or 'dark'const theme = resolveThemePreference( preference, matchMedia('(prefers-color-scheme: dark)').matches,); // 'light' or 'dark'writeThemePreference('example-theme', 'dark'); // false when the browser blocks storage
SEARCH_TEXT_LIMITS holds the lengths that keep titles and descriptions whole in search results, for build checks.
Generated from TSDoc
API reference
Every export of [email protected], 24 in all, with its signature, its errors, and an example.
Builds a standalone BreadcrumbList for a page whose structured data is assembled elsewhere, from the same steps its visible breadcrumb shows. A step without a URL, such as the current page, gets no item, as schema.org allows for the last step.
The steps, from the home page to this page, each with its absolute URL.
Returns
Record<string, unknown>
The BreadcrumbList's JSON-LD.
Example
import { buildBreadcrumbStructuredData } from 'jg-site';buildBreadcrumbStructuredData([ { name: 'Home', url: 'https://example.com/' }, { name: 'Blog', url: 'https://example.com/blog' }, { name: 'Release notes' },]);// a BreadcrumbList whose last ListItem has a name and a position, and no item
The name, the summary, and the documents, each a Markdown file.
Returns
string
The file's text.
Example
import { buildLlmsFullText } from 'jg-site';buildLlmsFullText({ name: 'jg-packages', summary: 'Packages for agents.', documents: ['# jg-fetch\n'] });// the title and the summary, a rule, then the jg-fetch document
Writes an llms.txt in the llmstxt.org format: the site's name as the title, its summary as a blockquote, optional details, then one ## section per group of links. Each link's label is escaped, and its description, when it has one, kept to one line. A section can carry a Markdown body instead of links, such as an install command in a code block, written as it is.
Signature
buildLlmsText(options: ILlmsTextOptions): string
Parameters
optionsILlmsTextOptions
The name, the summary, the details, and the sections.
Returns
string
The file's text.
Example
import { buildLlmsText } from 'jg-site';buildLlmsText({ name: 'jg-packages', summary: 'Small, tested TypeScript packages for coding agents.', sections: [ { heading: 'Packages', links: [ { title: 'jg-fetch', url: 'https://jg-packages.jesusgraterol.dev/packages/jg-fetch/index.md', description: 'A fetch wrapper that never throws.', }, ], }, ],});// a title, a blockquote, and a `## Packages` section with one link
Builds the JSON-LD for one page: the WebSite, with the pages it lists, for the home page, and a WebPage within it, with its breadcrumb and the source code it documents, for every other page.
Collapses prose into one line for a Markdown list item, so a description written across lines stays one item.
Signature
normalizeDescription(description: string): string
Parameters
descriptionstring
The description.
Returns
string
The description on one line, without surrounding whitespace.
Example
import { normalizeDescription } from 'jg-site';normalizeDescription('Typed stores,\n for pages and workers. '); // 'Typed stores, for pages and workers.'
Serializes JSON-LD for a <script type="application/ld+json">, escaping every <, so text in the data, such as a description that mentions </script>, can't end the script element.
Stores a preference under a key, and reports whether it could, because the browser can block storage. The page still applies the preference when it can't.