Analog User Guide - Site Configuration

Site-wide settings live in site.config.ts inside the active site directory. They describe the site itself rather than an individual post or page.

For the demo site:

sites/demo/
├── site.config.ts
└── next.config.ts

The optional next.config.ts is only needed for Next.js-specific settings such as remote image hosts or redirects.

Basic configuration

A minimal configuration contains four required fields:

import { type InputSiteConfig } from "@/lib/site/schema"
 
const config: InputSiteConfig = {
  siteUrl: "https://example.com",
  siteTitle: "Example Site",
  description: "Notes, projects, and other updates.",
  author: "Your Name",
}
 
export default config

Use the final production origin for siteUrl. It is used when generating canonical URLs, social metadata, and the RSS feed.

Favicons

Place favicon files under the site's public directory and reference them with public paths:

favicon: {
  ico: "/favicon/favicon.ico",
  svg: "/favicon/favicon.svg",
  png96x96: "/favicon/favicon-96x96.png",
  apple: "/favicon/apple-touch-icon.png",
  manifest192x192: "/favicon/web-app-manifest-192x192.png",
  manifest512x512: "/favicon/web-app-manifest-512x512.png",
},

Only the files used by the site need to be listed. A favicon generator such as RealFaviconGenerator can create the common formats and sizes.

Header and footer

The header controls the site logo, displayed title, and primary navigation:

header: {
  logo: "/favicon/favicon.svg",
  title: "Example Site",
  nav: [
    { label: "Articles", href: "/posts" },
    { label: "Tags", href: "/posts/tags" },
    { label: "News", href: "/news" },
    { label: "People", href: "/people" },
    { label: "About", href: "/about" },
  ],
},

Both logo and title are optional. Navigation links may point to pages in the site or to external URLs.

The footer can contain links with optional Tabler Icons:

footer: {
  socialIcons: [
    {
      label: "GitHub",
      href: "https://github.com/your-name",
      icon: "IconBrandGithub",
    },
    {
      label: "RSS Feed",
      href: "/rss.xml",
      icon: "IconRss",
    },
  ],
},

Sites hosted in mainland China may also provide ICP and public-security registration information:

footer: {
  beian: {
    icp: {
      code: "Example ICP record",
    },
    publicSecurity: {
      code: "Example public security record",
      href: "https://example.com",
    },
  },
},

The beian section may be omitted when it is not applicable.

Content behavior

The content section controls drafts, pagination, post ordering, and taxonomy aliases:

content: {
  includeDraft: false,
  post: {
    pageSize: 10,
    sortKey: "datePublish",
    sortDirection: "desc",
  },
  category: {
    aliases: {},
  },
  tag: {
    aliases: {
      Markdown: ["MDX"],
    },
  },
},

Posts can be sorted by datePublish, dateUpdate, or title in ascending or descending order. The defaults are reverse publication order with ten posts per page.

Aliases combine equivalent names under one category or tag. In the example above, posts tagged MDX are collected under the canonical Markdown tag.

Keep includeDraft disabled for a normal production deployment. When enabled, content marked with draft: true is included in the generated site.

Page summaries

Archive and taxonomy pages use default summaries. They can be replaced when the wording should match a particular site:

pageSummaries: {
  archive: "All published articles, collected in one place.",
  tags: "Explore articles by topic.",
  category: "Browse articles filed under “{name}”.",
  tag: "Browse articles tagged with “{name}”.",
  author: "Browse articles written by {name}.",
},

{name} is replaced with the current category, tag, or author name.

Analytics

Analytics are disabled when no provider is configured. Analog currently supports Umami:

analytics: {
  umami: {
    websiteId: "00000000-0000-0000-0000-000000000000",
  },
},

websiteId is the only required field. It is generated when a website is added to Umami.

The remaining options control script hosting, accepted domains, privacy behavior, and performance measurements:

analytics: {
  umami: {
    websiteId: "00000000-0000-0000-0000-000000000000",
    src: "https://cloud.umami.is/script.js",
    hostUrl: "https://analytics.example.com",
    domains: ["example.com", "www.example.com"],
    doNotTrack: true,
    excludeSearch: false,
    excludeHash: true,
    performance: false,
  },
},

Comments

Comments are disabled when no provider is configured. The current implementation supports Giscus:

comment: {
  provider: "giscus",
  repo: "your-name/your-repository",
  repoId: "R_example",
  category: "Announcements",
  categoryId: "DIC_example",
},

Use the values generated by Giscus rather than writing the IDs manually. The external setup process is described in Integrations.

Posts enable comments by default and can opt out with comment: false. Pages and author profiles disable them by default and can opt in with comment: true.

Social sharing

Default Open Graph and Twitter images are configured with socialShare:

socialShare: {
  defaultImages: ["/social-images-default.png"],
  twitterSite: "@your_name",
},

Place local images in the site's public directory. twitterSite is optional and must begin with @ when provided.

Content-specific descriptions and post covers can override these defaults. The relationship between summary and seo.description is described in Content Model.

Optional Next.js configuration

A site may provide its own next.config.ts:

import { type NextConfig } from "next"
 
const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "images.example.com",
        pathname: "/**",
      },
    ],
  },
}
 
export default nextConfig

The file is merged with the shared project configuration. Most sites only need it when they use remote images or define redirects. Remove it when no additional Next.js option is required.

See the Next.js configuration reference and remote image guide for additional options.

Validation

The configuration is checked when the site starts or builds. Missing required values, invalid URLs, and unsupported options are reported as configuration errors.

Post dates, authors, categories, covers, and other content-specific fields belong in the corresponding content files and are covered in Content Model.