Skip to main content
@noxion/core

Types

All types exported from @noxion/core:

import type {
  NoxionPage,
  BlogPage,
  DocsPage,
  PortfolioPage,
  BlogPost,        // backward-compat alias for BlogPage
  NoxionCollection,
  NoxionConfig,
  NoxionConfigInput,
  ThemeMode,
  NoxionLayout,
  NoxionPlugin,
  PluginFactory,
  PluginConfig,
  PageTypeDefinition,
  SchemaConventions,
  HeadTag,
  SitemapEntry,
  NoxionPageData,
  ExtendedRecordMap,
} from "@noxion/core";

NoxionPage​

The base type for all page types. A discriminated union based on pageType.

interface NoxionPage {
  id: string;
  title: string;
  slug: string;
  pageType: string;
  coverImage?: string;
  description?: string;
  published: boolean;
  lastEditedTime: string;
  frontmatter?: Record<string, string>;
  metadata: Record<string, unknown>;
  parent?: string;
  children?: string[];
  order?: number;
}
FieldTypeDescription
idstringNotion page ID (UUID without hyphens)
titlestringPage title from the Notion Title property
slugstringURL slug (e.g. "my-first-post")
pageTypestringDiscriminant: "blog", "docs", "portfolio", or custom
coverImagestring?Cover image URL (notion.so/image/... proxy URL)
descriptionstring?Page description for SEO meta tags
publishedbooleanWhether the page is published (Public checkbox)
lastEditedTimestringISO datetime of last edit
frontmatterRecord<string, string>?Raw frontmatter key-value pairs from the first code block
metadataRecord<string, unknown>Type-specific metadata (date, tags, section, etc.)

BlogPage​

Blog post with date, tags, category, and author metadata.

interface BlogPage extends NoxionPage {
  pageType: "blog";
  metadata: {
    date: string;
    tags: string[];
    category?: string;
    author?: string;
  };
}

Access metadata:

const page: BlogPage = /* ... */;
page.metadata.date;     // "2025-02-01"
page.metadata.tags;     // ["react", "typescript"]
page.metadata.category; // "Web Dev"
page.metadata.author;   // "Jane Doe"

DocsPage​

Documentation page with section, order, and version metadata.

interface DocsPage extends NoxionPage {
  pageType: "docs";
  metadata: {
    section?: string;
    version?: string;
    editUrl?: string;
  };
}

Access metadata:

const page: DocsPage = /* ... */;
page.metadata.section;  // "Getting Started"
page.metadata.version;  // "latest"
page.metadata.editUrl;  // "https://github.com/..."

PortfolioPage​

Portfolio project with technologies, URL, year, and featured flag.

interface PortfolioPage extends NoxionPage {
  pageType: "portfolio";
  metadata: {
    technologies?: string[];
    projectUrl?: string;
    year?: string;
    featured?: boolean;
  };
}

Access metadata:

const page: PortfolioPage = /* ... */;
page.metadata.technologies; // ["React", "TypeScript"]
page.metadata.projectUrl;   // "https://example.com"
page.metadata.year;         // "2025"
page.metadata.featured;     // true

BlogPost​

Backward-compatible alias for BlogPage. Kept for one version cycle.

type BlogPost = BlogPage;
Migration

If you're upgrading from v0.1, replace post.date with post.metadata.date, post.tags with post.metadata.tags, etc. See the Migration Guide for details.

NoxionCollection​

A collection maps a Notion database to a page type.

interface NoxionCollection {
  name?: string;
  databaseId: string;
  pageType: string;
  pathPrefix?: string;
  schema?: Record<string, string>;
}
FieldTypeRequiredDescription
namestring—Display name
databaseIdstring✅Notion database page ID
pageTypestring✅Page type identifier
pathPrefixstring—URL prefix (e.g. "docs" → /docs/[slug])
schemaRecord<string, string>—Manual property name mapping overrides

PageTypeDefinition​

Defines a custom page type, registered via the registerPageTypes plugin hook.

interface PageTypeDefinition {
  name: string;
  schemaConventions?: SchemaConventions;
  defaultTemplate?: string;
  defaultLayout?: string;
  routes?: (page: NoxionPage) => string;
  sortBy?: { field: string; order: "asc" | "desc" };
  sitemapConfig?: { priority: number; changefreq: "daily" | "weekly" | "monthly" };
  structuredDataType?: string;
  metadataConfig?: { openGraphType: "article" | "website" };
}

SchemaConventions​

Maps metadata field names to their default Notion property names for a page type.

interface SchemaConventions {
  [fieldName: string]: {
    names: string[];
    type?: string;
  };
}

Built-in conventions:

Page TypeField → Notion Property
Blogdate → "Published", tags → "Tags", category → "Category", author → "Author"
Docssection → "Section", order → "Order", version → "Version"
Portfoliotechnologies → "Technologies", projectUrl → "Project URL", year → "Year", featured → "Featured"

NoxionConfig​

The fully-resolved configuration object. All optional fields have defaults applied.

interface NoxionConfig {
  rootNotionPageId?: string;
  rootNotionSpaceId?: string;
  name: string;
  domain: string;
  author: string;
  description: string;
  language: string;
  defaultTheme: ThemeMode;
  defaultPageType: string;
  revalidate: number;
  revalidateSecret?: string;
  plugins?: PluginConfig[];
  collections?: NoxionCollection[];
  theme?: NoxionThemeConfig;
  layout?: NoxionLayout;
  components?: ComponentOverrides;
}

NoxionConfigInput​

The input type accepted by defineConfig(). All optional fields can be omitted.

interface NoxionConfigInput {
  rootNotionPageId?: string;
  rootNotionSpaceId?: string;
  name: string;
  domain: string;
  author: string;
  description: string;
  language?: string;
  defaultTheme?: ThemeMode;
  defaultPageType?: string;
  revalidate?: number;
  revalidateSecret?: string;
  plugins?: PluginConfig[];
  collections?: NoxionCollection[];
  theme?: NoxionThemeConfig;
  layout?: NoxionLayout;
  components?: ComponentOverrides;
}

ThemeMode​

type ThemeMode = "system" | "light" | "dark";

NoxionLayout​

type NoxionLayout = "single-column" | "sidebar-left" | "sidebar-right";

NoxionPageData​

Combines a NoxionPage with its ExtendedRecordMap for rendering.

interface NoxionPageData {
  recordMap: ExtendedRecordMap;
  post: NoxionPage;
}

PluginFactory​

Type for plugin factory functions that accept configuration options.

type PluginFactory<Options = unknown, Content = unknown> = (
  options: Options
) => NoxionPlugin<Content>;

ExtendedRecordMap​

Re-exported from notion-types. Contains the complete Notion page data. Passed directly to <NotionPage recordMap={...} />.

import type { ExtendedRecordMap } from "@noxion/core";

PluginConfig​

type PluginConfig =
  | PluginModule
  | [PluginModule, unknown]
  | false;

Where PluginModule = NoxionPlugin | PluginFactory.

The false variant allows conditionally disabling plugins:

plugins: [
  createRSSPlugin({ feedPath: "/feed.xml" }),
  process.env.NODE_ENV === "production" && createAnalyticsPlugin({ ... }),
].filter(Boolean),

Type guards​

import { isBlogPage, isDocsPage, isPortfolioPage } from "@noxion/core";

const page: NoxionPage = /* ... */;

if (isBlogPage(page)) {
  page.metadata.date;  // TypeScript knows this is BlogPage
}

if (isDocsPage(page)) {
  page.metadata.section;  // TypeScript knows this is DocsPage
}

if (isPortfolioPage(page)) {
  page.metadata.technologies;  // TypeScript knows this is PortfolioPage
}
On this page