@kamod-ch/preactpress 1.0.0

package/src/client/types.ts

@@ -0,0 +1,37 @@
+import type { ComponentType } from 'preact'
+import type { OutlineItem, ResolvedI18n, ResolvedLocale, SiteData, ThemeConfig } from '../node/siteConfig.js'
+
+interface BasePageView {
+  title?: string
+  description?: string
+  tags?: string[]
+  image?: string
+  pageType?: 'website' | 'article'
+  meta: Record<string, unknown>
+  headings: OutlineItem[]
+  relativePath?: string
+  lastUpdated?: string
+}
+
+export interface HtmlPageView extends BasePageView {
+  kind: 'markdown'
+  html: string
+}
+
+export interface MdxPageView extends BasePageView {
+  kind: 'mdx'
+  Component: ComponentType<{ components?: Record<string, ComponentType<Record<string, unknown>>> }>
+}
+
+export type PageView = HtmlPageView | MdxPageView
+
+export interface LayoutProps {
+  site: SiteData
+  themeConfig: ThemeConfig
+  routePath: string
+  page?: PageView
+  i18n?: ResolvedI18n
+  locale?: ResolvedLocale
+  locales?: ResolvedLocale[]
+  localizeRoute?: (locale: ResolvedLocale) => string
+}

package/src/client/usePageHead.ts

@@ -0,0 +1,212 @@
+import { useEffect } from 'preact/hooks'
+import type { ResolvedI18n, SiteData } from '../node/siteConfig.js'
+import {
+  resolvePageHeadMeta,
+  titleTemplateFromMeta,
+  type PageMetaInput
+} from '../shared/pageMeta.js'
+import { headTagsFromMeta } from '../shared/pageHead.js'
+import type { HeadTag } from '../node/siteConfig.js'
+import { canonicalUrl, publicUrl } from '../shared/url.js'
+import { localizedRouteForLocale, siteForRoute } from '../shared/locale.js'
+
+function upsertMeta(
+  selector: 'name' | 'property',
+  key: string,
+  content: string
+): void {
+  if (!content) return
+  let el = document.head.querySelector(
+    `meta[${selector}="${key}"]`
+  ) as HTMLMetaElement | null
+  if (!el) {
+    el = document.createElement('meta')
+    el.setAttribute(selector, key)
+    document.head.appendChild(el)
+  }
+  el.content = content
+}
+
+function removeMeta(selector: 'name' | 'property', key: string): void {
+  document.head
+    .querySelectorAll(`meta[${selector}="${key}"]`)
+    .forEach((el) => el.remove())
+}
+
+function appendMeta(selector: 'name' | 'property', key: string, content: string): void {
+  if (!content) return
+  const el = document.createElement('meta')
+  el.setAttribute(selector, key)
+  el.content = content
+  document.head.appendChild(el)
+}
+
+function upsertCanonical(href: string): void {
+  if (!href) return
+  let el = document.head.querySelector('link[rel="canonical"]') as HTMLLinkElement | null
+  if (!el) {
+    el = document.createElement('link')
+    el.rel = 'canonical'
+    document.head.appendChild(el)
+  }
+  el.href = href
+}
+
+function removeCanonical(): void {
+  document.head
+    .querySelectorAll('link[rel="canonical"]')
+    .forEach((el) => el.remove())
+}
+
+function replaceAlternates(opts: {
+  site: SiteData
+  i18n: ResolvedI18n | undefined
+  route: string
+  routes?: ReadonlySet<string>
+}): void {
+  document.head
+    .querySelectorAll('link[rel="alternate"][hreflang]')
+    .forEach((el) => el.remove())
+  if (!opts.site.url || !opts.i18n) return
+  for (const locale of opts.i18n.locales) {
+    const route = localizedRouteForLocale(opts.route, locale, opts.i18n, opts.routes)
+    if (opts.routes && !opts.routes.has(route)) continue
+    const el = document.createElement('link')
+    el.rel = 'alternate'
+    el.hreflang = locale.lang
+    el.href = canonicalUrl({ url: opts.site.url, base: opts.site.base, route })
+    document.head.appendChild(el)
+  }
+}
+
+function upsertHeadTag(tag: HeadTag): void {
+  const [name, attrs, content] = tag
+  if (name === 'meta') {
+    const key = 'name' in attrs && attrs.name ? 'name' : 'property' in attrs ? 'property' : undefined
+    if (key && typeof attrs[key] === 'string') {
+      upsertMeta(key as 'name' | 'property', String(attrs[key]), String(attrs.content ?? ''))
+      return
+    }
+  }
+  if (name === 'link' && attrs.rel && typeof attrs.href === 'string') {
+    let el = document.head.querySelector(
+      `link[rel="${attrs.rel}"]${attrs.hreflang ? `[hreflang="${attrs.hreflang}"]` : ''}`
+    ) as HTMLLinkElement | null
+    if (!el) {
+      el = document.createElement('link')
+      for (const [key, value] of Object.entries(attrs)) {
+        if (value != null && value !== false) el.setAttribute(key, String(value))
+      }
+      document.head.appendChild(el)
+    } else {
+      el.href = String(attrs.href)
+    }
+    return
+  }
+  if (name === 'script') {
+    const id = typeof attrs.id === 'string' ? attrs.id : undefined
+    let el = id ? (document.getElementById(id) as HTMLScriptElement | null) : null
+    if (!el) {
+      el = document.createElement('script')
+      for (const [key, value] of Object.entries(attrs)) {
+        if (value != null && value !== false) el.setAttribute(key, String(value))
+      }
+      el.textContent = content ?? ''
+      document.head.appendChild(el)
+    }
+  }
+}
+
+function resolveMetaImage(site: SiteData, image: string | undefined): string | undefined {
+  if (!image) return undefined
+  if (/^(?:[a-z]+:)?\/\//i.test(image)) return image
+  return site.url
+    ? `${site.url}${publicUrl(site.base, image)}`
+    : publicUrl(site.base, image)
+}
+
+export function usePageHead(opts: {
+  site: SiteData
+  i18n?: ResolvedI18n
+  routes?: ReadonlySet<string>
+  route: string
+  page: PageMetaInput | undefined
+}): void {
+  const { site, i18n, routes, route, page } = opts
+  const activeSite = siteForRoute(site, route, i18n)
+  const pageTitle = page?.title
+  const pageDescription = page?.description
+  const pageTags = page?.tags
+  const pageImage = page?.image
+  const pageType = page?.pageType
+  const pageKind = page?.kind
+  const pageHtml = page?.kind === 'markdown' ? page.html : undefined
+  const pageMeta = page?.meta
+
+  useEffect(() => {
+    const head = resolvePageHeadMeta(
+      pageKind === 'markdown'
+        ? {
+            title: pageTitle,
+            titleTemplate: titleTemplateFromMeta(pageMeta),
+            description: pageDescription,
+            tags: pageTags,
+            image: pageImage,
+            pageType,
+            kind: 'markdown',
+            html: pageHtml
+          }
+        : pageKind
+          ? {
+              title: pageTitle,
+              titleTemplate: titleTemplateFromMeta(pageMeta),
+              description: pageDescription,
+              tags: pageTags,
+              image: pageImage,
+              pageType,
+              kind: pageKind
+            }
+          : undefined,
+      activeSite
+    )
+
+    for (const tag of headTagsFromMeta(pageMeta)) upsertHeadTag(tag)
+
+    document.title = head.title
+
+    upsertMeta('name', 'description', head.description)
+    upsertMeta('property', 'og:title', head.title)
+    upsertMeta('property', 'og:description', head.description)
+    upsertMeta('property', 'og:type', head.pageType)
+    upsertMeta('name', 'twitter:card', head.image ? 'summary_large_image' : 'summary')
+    upsertMeta('name', 'twitter:title', head.title)
+    upsertMeta('name', 'twitter:description', head.description)
+    removeMeta('name', 'keywords')
+    removeMeta('property', 'article:tag')
+    for (const tag of head.tags) appendMeta('property', 'article:tag', tag)
+
+    const image = resolveMetaImage(activeSite, head.image)
+    if (image) {
+      upsertMeta('property', 'og:image', image)
+      upsertMeta('name', 'twitter:image', image)
+    } else {
+      removeMeta('property', 'og:image')
+      removeMeta('name', 'twitter:image')
+    }
+
+    const canonical = canonicalUrl({ url: activeSite.url, base: activeSite.base, route })
+    if (canonical) {
+      upsertMeta('property', 'og:url', canonical)
+      upsertCanonical(canonical)
+    } else {
+      removeMeta('property', 'og:url')
+      removeCanonical()
+    }
+
+    replaceAlternates({ site: activeSite, i18n, route, routes })
+
+    if (document.documentElement.lang !== activeSite.lang) {
+      document.documentElement.lang = activeSite.lang
+    }
+  }, [activeSite, i18n, route, routes, pageTitle, pageDescription, pageTags, pageImage, pageType, pageKind, pageHtml, pageMeta])
+}

package/src/client/useSiteSearch.ts

@@ -0,0 +1,57 @@
+import { useEffect, useMemo, useState } from 'preact/hooks'
+import { publicUrl } from '../shared/url.js'
+
+export interface SearchEntry {
+  route: string
+  locale?: string
+  title?: string
+  description?: string
+  excerpt?: string
+  tags?: string[]
+}
+
+export function useSiteSearch(base: string, query: string, locale?: string): SearchEntry[] {
+  const [entries, setEntries] = useState<SearchEntry[]>([])
+
+  useEffect(() => {
+    let cancelled = false
+    fetch(publicUrl(base, 'preactpress-search.json'), { credentials: 'same-origin' })
+      .then((res) => res.ok ? res.json() : [])
+      .then((data) => {
+        if (!cancelled && Array.isArray(data)) setEntries(data as SearchEntry[])
+      })
+      .catch(() => {
+        if (!cancelled) setEntries([])
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [base])
+
+  return useMemo(() => {
+    const needle = query.trim().toLowerCase()
+    if (!needle) return []
+    return entries
+      .filter((entry) => !locale || entry.locale === locale)
+      .map((entry) => ({ entry, score: scoreEntry(entry, needle) }))
+      .filter(({ score }) => score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 8)
+      .map(({ entry }) => entry)
+  }, [entries, locale, query])
+}
+
+function scoreEntry(entry: SearchEntry, query: string): number {
+  const title = entry.title?.toLowerCase() ?? ''
+  const tags = entry.tags?.join(' ').toLowerCase() ?? ''
+  const description = entry.description?.toLowerCase() ?? ''
+  const excerpt = entry.excerpt?.toLowerCase() ?? ''
+  let score = 0
+  if (title === query) score += 20
+  if (title.includes(query)) score += 10
+  if (tags.includes(query)) score += 6
+  if (description.includes(query)) score += 4
+  if (excerpt.includes(query)) score += 2
+  if (entry.route.toLowerCase().includes(query)) score += 1
+  return score
+}

package/src/client/virtual.d.ts

@@ -0,0 +1,103 @@
+/// <reference types="vite/client" />
+
+declare module '@docsearch/css'
+
+declare module '*.mdx' {
+  import type { ComponentType } from 'preact'
+  const MdxPage: ComponentType<{
+    components?: Record<string, ComponentType<Record<string, unknown>>>
+  }>
+  export default MdxPage
+}
+
+declare module 'virtual:preactpress-pages' {
+  import type { ComponentType } from 'preact'
+
+  export const pages: Record<
+    string,
+    | {
+      kind: 'markdown'
+      meta: Record<string, unknown>
+      html: string
+      title?: string
+      description?: string
+      tags?: string[]
+      image?: string
+      pageType?: 'website' | 'article'
+      headings: { id: string; text: string; level: number }[]
+      relativePath?: string
+      lastUpdated?: string
+    }
+    | {
+      kind: 'mdx'
+      Component: ComponentType<{
+        components?: Record<string, ComponentType<Record<string, unknown>>>
+      }>
+      meta: Record<string, unknown>
+      title?: string
+      description?: string
+      tags?: string[]
+      image?: string
+      pageType?: 'website' | 'article'
+      headings: { id: string; text: string; level: number }[]
+      relativePath?: string
+      lastUpdated?: string
+    }
+  >
+  export const pagesMeta: Record<
+    string,
+    {
+      kind: 'markdown' | 'mdx'
+      meta: Record<string, unknown>
+      title?: string
+      description?: string
+      tags?: string[]
+      image?: string
+      pageType?: 'website' | 'article'
+      headings: { id: string; text: string; level: number }[]
+      relativePath?: string
+      lastUpdated?: string
+    }
+  >
+  export const mdxLoaders: Record<
+    string,
+    () => Promise<{
+      default: ComponentType<{
+        components?: Record<string, ComponentType<Record<string, unknown>>>
+      }>
+    }>
+  >
+  export const routes: string[]
+}
+
+declare module 'virtual:preactpress-site' {
+  export const mpa: boolean
+  export const site: {
+    title: string
+    description: string
+    base: string
+    lang: string
+    url?: string
+  }
+  export const themeConfig: {
+    logo?: import('../node/siteConfig.js').ThemeLogo
+    labels?: import('../node/siteConfig.js').ThemeLabels
+    nav?: import('../node/siteConfig.js').NavItem[]
+    sidebar?: import('../node/siteConfig.js').SidebarConfig
+    outline?: boolean | import('../shared/pageChrome.js').PageOutlineConfig
+    search?: import('../shared/search.js').SearchConfig
+    socialLinks?: import('../shared/socialIcons.js').SocialLink[]
+    tags?: boolean
+    footer?: string
+    editLink?: { pattern: string; text?: string }
+    lastUpdated?: boolean
+  }
+  export const i18n: import('../node/siteConfig.js').ResolvedI18n | undefined
+}
+
+declare module 'virtual:preactpress-layout' {
+  import type { FunctionalComponent } from 'preact'
+  import type { LayoutProps } from './types.js'
+  const Layout: FunctionalComponent<LayoutProps>
+  export default Layout
+}

package/src/shared/contentChunk.ts

@@ -0,0 +1,14 @@
+export const CONTENT_CHUNK_DIR = 'preactpress-content'
+
+export function encodeContentRoute(route: string): string {
+  if (route === '/') return '_index.json'
+  const clean = route.replace(/^\/+|\/+$/g, '')
+  return `${clean
+    .split('/')
+    .map((part) => encodeURIComponent(part))
+    .join('__')}.json`
+}
+
+export function contentChunkPath(route: string): string {
+  return `${CONTENT_CHUNK_DIR}/${encodeContentRoute(route)}`
+}

package/src/shared/contentSchema.ts

@@ -0,0 +1,85 @@
+/** Author metadata for articles, magazines, and blogs. */
+export interface Author {
+  name: string
+  slug?: string
+  avatar?: string
+}
+
+/** Category or rubric metadata for editorial content. */
+export interface ContentCategory {
+  name: string
+  slug?: string
+}
+
+/** Common article frontmatter fields beyond built-in page metadata. */
+export interface ArticleFrontmatter {
+  title?: string
+  description?: string
+  tags?: string[]
+  author?: string | Author
+  category?: string | ContentCategory
+  readTime?: string
+  draft?: boolean
+}
+
+/** Normalized article record produced from content loaders or hooks. */
+export interface ArticlePost {
+  title: string
+  route: string
+  url: string
+  description?: string
+  tags?: string[]
+  author?: Author
+  category?: ContentCategory
+  readTime?: string
+}
+
+export function parseAuthor(value: unknown): Author | undefined {
+  if (typeof value === 'string' && value.trim()) {
+    return { name: value.trim() }
+  }
+  if (!value || typeof value !== 'object') return undefined
+  const record = value as Record<string, unknown>
+  const name = typeof record.name === 'string' ? record.name.trim() : ''
+  if (!name) return undefined
+  const slug = typeof record.slug === 'string' && record.slug.trim() ? record.slug.trim() : undefined
+  const avatar =
+    typeof record.avatar === 'string' && record.avatar.trim() ? record.avatar.trim() : undefined
+  return { name, slug, avatar }
+}
+
+export function parseCategory(value: unknown): ContentCategory | undefined {
+  if (typeof value === 'string' && value.trim()) {
+    return { name: value.trim() }
+  }
+  if (!value || typeof value !== 'object') return undefined
+  const record = value as Record<string, unknown>
+  const name = typeof record.name === 'string' ? record.name.trim() : ''
+  if (!name) return undefined
+  const slug = typeof record.slug === 'string' && record.slug.trim() ? record.slug.trim() : undefined
+  return { name, slug }
+}
+
+export function articleFromFrontmatter(opts: {
+  route: string
+  url: string
+  title?: string
+  description?: string
+  tags?: string[]
+  frontmatter: Record<string, unknown>
+}): ArticlePost {
+  const fm = opts.frontmatter as ArticleFrontmatter
+  const title = (opts.title ?? fm.title ?? 'Untitled').trim()
+  const description = (opts.description ?? fm.description)?.trim() || undefined
+  const tags = (opts.tags ?? fm.tags)?.filter((tag) => tag.trim()).map((tag) => tag.trim())
+  return {
+    title,
+    route: opts.route,
+    url: opts.url,
+    description,
+    tags,
+    author: parseAuthor(fm.author),
+    category: parseCategory(fm.category) ?? (tags?.[0] ? { name: tags[0] } : undefined),
+    readTime: typeof fm.readTime === 'string' && fm.readTime.trim() ? fm.readTime.trim() : undefined
+  }
+}

package/src/shared/deadLinks.ts

@@ -0,0 +1,33 @@
+export type IgnoreDeadLinks =
+  | boolean
+  | string[]
+  | ((href: string, ctx: { from: string; route?: string }) => boolean)
+
+function patternToRegExp(pattern: string): RegExp {
+  const escaped = pattern
+    .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '§§')
+    .replace(/\*/g, '[^/]*')
+    .replace(/§§/g, '.*')
+  return new RegExp(`^${escaped}$`)
+}
+
+function matchesPattern(pattern: string, href: string, route?: string): boolean {
+  if (pattern === href || (route && pattern === route)) return true
+  if (pattern.includes('*')) {
+    const re = patternToRegExp(pattern)
+    return re.test(href) || (route ? re.test(route) : false)
+  }
+  return href.includes(pattern) || (route ? route.includes(pattern) : false)
+}
+
+export function shouldIgnoreDeadLink(
+  href: string,
+  ignore: IgnoreDeadLinks | undefined,
+  ctx: { from: string; route?: string }
+): boolean {
+  if (!ignore) return false
+  if (ignore === true) return true
+  if (typeof ignore === 'function') return ignore(href, ctx)
+  return ignore.some((pattern) => matchesPattern(pattern, href, ctx.route))
+}

package/src/shared/escapeHtml.ts

@@ -0,0 +1,11 @@
+export function escapeHtml(s: string): string {
+  return s
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+}
+
+export function escapeAttr(s: string): string {
+  return escapeHtml(s)
+}

package/src/shared/index.ts

@@ -0,0 +1,83 @@
+export { contentChunkPath, encodeContentRoute } from './contentChunk.js'
+export { escapeAttr, escapeHtml } from './escapeHtml.js'
+export {
+  PAGE_LAYOUTS,
+  DEFAULT_TITLE_TEMPLATE,
+  excerptFromHtml,
+  formatTitleTemplate,
+  isPageLayout,
+  pageLayoutFromMeta,
+  resolvePageHeadMeta,
+  resolvePageMeta,
+  titleTemplateFromMeta,
+  type PageFrontmatter,
+  type PageLayout,
+  type PageMetaInput
+} from './pageMeta.js'
+export {
+  articleFromFrontmatter,
+  parseAuthor,
+  parseCategory,
+  type ArticleFrontmatter,
+  type ArticlePost,
+  type Author,
+  type ContentCategory
+} from './contentSchema.js'
+export { headTagsFromMeta } from './pageHead.js'
+export {
+  allSidebarGroups,
+  flattenNavLeafItems,
+  flattenSidebarItems,
+  flattenSidebarLeafItems,
+  isPathSidebarConfig,
+  resolveSidebarForRoute,
+  type SidebarConfig
+} from './sidebar.js'
+export {
+  applyRouteRewrites,
+  normalizeRewriteRoute,
+  type RouteRewrites
+} from './rewrites.js'
+export {
+  defaultLabelsForLang,
+  resolveThemeLabels,
+  type ResolvedThemeLabels
+} from './themeLabels.js'
+export {
+  filterHeadingsForOutline,
+  parseFeatures,
+  parseHero,
+  resolvePageChrome,
+  type Feature,
+  type FeatureIcon,
+  type Hero,
+  type HeroAction,
+  type PageAside,
+  type PageOutlineConfig,
+  type PageOutlineLevels,
+  type ResolvedPageChrome,
+  type ThemeableImage
+} from './pageChrome.js'
+export {
+  algoliaOptionsFromSearch,
+  getRelativeDocSearchUrl,
+  isAlgoliaSearchEnabled,
+  isLocalSearchEnabled,
+  resolveAlgoliaOptions,
+  resolveSearchProvider,
+  validateAlgoliaCredentials,
+  type AlgoliaSearchConfig,
+  type AlgoliaSearchOptions,
+  type LocalSearchConfig,
+  type SearchConfig,
+  type SearchProvider
+} from './search.js'
+export {
+  socialIconSvg,
+  socialLinkLabel,
+  type SocialLink,
+  type SocialLinkIcon
+} from './socialIcons.js'
+export { normalizeRoute, routeFromPathname } from './route.js'
+export { slugifySegment, uniqueSlug } from './slug.js'
+export { slugifyTagSegment, tagIndexPageRoute } from './tags.js'