### Start Noxion Blog Development Server

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/quick-start.md

This snippet shows the commands to install dependencies and start the development server for a Noxion blog. Once running, the blog can be accessed locally, and Notion posts will appear automatically.

```bash
bun install
bun run dev
```

--------------------------------

### Deploy Noxion Blog with Docker

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/quick-start.md

This snippet shows the command to start a Noxion blog using Docker Compose. This is an alternative deployment method for running the blog locally or on a server with Docker installed.

```bash
docker compose up
```

--------------------------------

### Start Demo App with Bun

Source: https://github.com/jiwonme/noxion/blob/main/README.md

Navigates to the 'apps/web' directory and starts the development server for the demo application using Bun. This is useful for local development and previewing changes.

```shell
cd apps/web && bun run dev
```

--------------------------------

### Start Local Development Server with Yarn

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/README.md

Starts a local development server for the Docusaurus website. Changes are reflected live without requiring a server restart. Opens the site in a browser window.

```bash
yarn start
```

--------------------------------

### Configure Noxion Blog Environment Variables

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/quick-start.md

This snippet demonstrates how to set up the environment variables for a Noxion blog after scaffolding. It involves copying an example environment file and editing it with specific site details.

```bash
cd my-blog
cp .env.example .env
```

```bash
NOTION_PAGE_ID=abc123def456...
SITE_DOMAIN=myblog.com
SITE_NAME=My Blog
SITE_AUTHOR=Your Name
SITE_DESCRIPTION=A blog about things I find interesting
```

--------------------------------

### Install Dependencies with Yarn

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/README.md

Installs project dependencies using the Yarn package manager. This is typically the first step before running other commands.

```bash
yarn
```

--------------------------------

### Configure Notion Integration Token

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/notion-setup.md

Shows how to set the NOTION_TOKEN environment variable for accessing private Notion pages. This requires creating an integration in Notion and adding its token to your .env file.

```bash
NOTION_TOKEN=secret_xxx...
```

--------------------------------

### Scaffold Noxion Blog with Bun CLI

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/quick-start.md

This snippet shows how to create a new Noxion blog project using the Bun CLI. It covers both interactive and non-interactive modes for setting up project details like Notion page ID, site name, and domain.

```bash
bun create noxion my-blog
```

```bash
bun create noxion my-blog \
  --yes \
  --notion-id=abc123def456 \
  --name="My Blog" \
  --domain=myblog.com \
  --author="Your Name"
```

--------------------------------

### Install Dependencies with Bun

Source: https://github.com/jiwonme/noxion/blob/main/README.md

This command installs all project dependencies for the Noxion monorepo using the Bun package manager. It's a standard step for local development.

```bash
# Install dependencies
bun install
```

--------------------------------

### Deploy Noxion Blog with Vercel CLI

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/quick-start.md

This snippet shows the command to deploy a Noxion blog using the Vercel CLI. It's recommended to add the same environment variables configured locally to the Vercel dashboard for a successful deployment.

```bash
vercel
```

--------------------------------

### Build Static Website Content with Yarn

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/README.md

Generates the static content for the website into the 'build' directory. This output can be hosted on any static content hosting service.

```bash
yarn build
```

--------------------------------

### Scaffold a New Noxion Blog with Bun

Source: https://github.com/jiwonme/noxion/blob/main/README.md

This command uses the Bun package manager to create a new Next.js blog project scaffolded by Noxion. It's the quickest way to start a new blog with Noxion.

```bash
bun create noxion my-blog
cd my-blog
# Edit .env with your Notion page ID
bun run dev
```

--------------------------------

### Frontmatter Overrides in Notion

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/notion-setup.md

Illustrates how to use a code block at the beginning of a Notion page to override metadata like URL slug, title, and description. Comments starting with '#' are ignored.

```yaml
cleanUrl: /my-custom-slug
title: Custom SEO Title | Site Name
description: Custom meta description for search engines
floatFirstTOC: right
```

```yaml
cleanUrl: /my-post
# title: Draft title (commented out)
description: My description
```

--------------------------------

### Scaffold a New Noxion Blog Project with create-noxion

Source: https://context7.com/jiwonme/noxion/llms.txt

The `create-noxion` CLI tool scaffolds a new Next.js blog project with Noxion packages pre-configured. It sets up environment templates and a demo structure, simplifying project initialization. After creation, you need to configure your Notion page ID in the `.env` file and start the development server.

```bash
# Create a new Noxion blog project
bun create noxion my-blog

# Navigate to the project directory
cd my-blog

# Configure your Notion page ID in .env
echo "NOTION_PAGE_ID=your-notion-database-page-id" > .env

# Start the development server
bun run dev

# Open http://localhost:3000 to see your blog
```

--------------------------------

### Quick Deploy with Docker Compose

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/deployment/docker.md

This snippet demonstrates the quickest way to deploy the Noxion web application using Docker Compose. It involves navigating to the application directory, copying and filling in environment variables, and then starting the services in detached mode. Access the application at http://localhost:3000.

```bash
cd apps/web
cp .env.example .env   # fill in your values
docker compose up -d
```

--------------------------------

### Deploy Website with Yarn (SSH)

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/README.md

Deploys the Docusaurus website using SSH. This command builds the site and pushes it to the 'gh-pages' branch, suitable for GitHub Pages.

```bash
USE_SSH=true yarn deploy
```

--------------------------------

### Extract Notion Page ID from URL

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/notion-setup.md

Demonstrates how to extract the unique 32-character page ID from a Notion database URL. This ID is crucial for Noxion to access your Notion content.

```text
https://notion.so/your-workspace/My-Database-abc123def456...
                                                ^^^^^^^^^^^^^^^^
                                                This is your page ID
```

--------------------------------

### Usage Example: Rendering PostList in a Server Component

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/renderer/post-list.md

Demonstrates how to fetch post data using an async function (e.g., getAllPosts) and then render the PostList component in a React Server Component. It shows mapping fetched posts to the expected PostCardProps format.

```tsx
// app/page.tsx (Server Component)
import { PostList } from "@noxion/renderer";
import { getAllPosts } from "@/lib/notion";

export default async function HomePage() {
  const posts = await getAllPosts();

  return (
    <main>
      <h1>My Blog</h1>
      <PostList
        posts={posts.map((p) => ({
          id: p.id,
          title: p.title,
          slug: p.slug,
          date: p.date,
          tags: p.tags,
          coverImage: p.coverImage,
          category: p.category,
          description: p.description,
          author: p.author,
        }))}
      />
    </main>
  );
}
```

--------------------------------

### Deploy Website with Yarn (No SSH)

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/README.md

Deploys the Docusaurus website without using SSH. Requires specifying the GitHub username. This command builds the site and pushes it to the 'gh-pages' branch.

```bash
GIT_USER=<Your GitHub username> yarn deploy
```

--------------------------------

### Enable Image Optimization with Next.js Image

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/renderer/notion-page.md

This example shows how to integrate `next/image` with the NotionPage component for optimized image loading. By passing the `Image` component from 'next/image' to the `nextImage` prop, the component will automatically handle AVIF/WebP conversion and other optimizations provided by Next.js.

```tsx
import Image from "next/image";
import { NotionPage } from "@noxion/renderer";

<NotionPage
  recordMap={recordMap}
  rootPageId={post.id}
  nextImage={Image}
/>;
```

--------------------------------

### NoxionThemeProvider Component Setup

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/renderer/theme-provider.md

The NoxionThemeProvider component is essential for providing theme context to all Noxion components. It should wrap your entire application or at least all components that utilize Noxion's theming features. It accepts a theme configuration and an initial color mode.

```tsx
import { NoxionThemeProvider } from "@noxion/renderer";

// Wrap your app with NoxionThemeProvider
<NoxionThemeProvider theme={yourThemeConfig} defaultMode="dark">
  {/* Your app components */}
</NoxionThemeProvider>
```

--------------------------------

### Deploy Noxion Blog with Docker

Source: https://github.com/jiwonme/noxion/blob/main/README.md

These Docker commands show how to build and run a Noxion blog application. It covers building the Docker image and running it as a container, including how to set environment variables for configuration.

```bash
# Build
docker build -t noxion ./apps/web

# Run
docker run -p 3000:3000 \
  -e NOTION_PAGE_ID=abc123 \
  -e SITE_DOMAIN=myblog.com \
  noxion
```

--------------------------------

### Parse Key-Value Pairs from String

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/core/frontmatter.md

Parses a multi-line string containing key: value pairs into a JavaScript object. Lines starting with '#' are ignored as comments. Useful for processing frontmatter content.

```typescript
import { parseKeyValuePairs } from "@noxion/core";

const text = `
cleanUrl: /my-post
title: My Post
# description: (draft)
floatFirstTOC: right
`;
const parsed = parseKeyValuePairs(text);
// Example output: { cleanUrl: "/my-post", title: "My Post", floatFirstTOC: "right" }
```

--------------------------------

### CLI Tool: create-noxion

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/overview.md

CLI scaffolding tool for creating Noxion projects.

```APIDOC
## CLI Tool

### `create-noxion`

#### Description
Command-line interface tool for scaffolding new Noxion projects.

#### Method
`CLI Command`

#### Endpoint
N/A (Command-line execution)
```

--------------------------------

### Usage Example: Adding JSON-LD to a Next.js Page

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/adapter-nextjs/structured-data.md

Demonstrates how to use the generated JSON-LD objects within a Next.js page component. It shows how to embed the structured data using a script tag with `dangerouslySetInnerHTML`.

```tsx
// app/[slug]/page.tsx
const blogPostingLd = generateBlogPostingLD(post, siteConfig);
const breadcrumbLd = generateBreadcrumbLD(post, siteConfig);

return (
  <article>
    <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(blogPostingLd) }} />
    <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(breadcrumbLd) }} />
    <NotionPage recordMap={recordMap} rootPageId={post.id} />
  </article>
);
```

--------------------------------

### Build All Packages with Bun

Source: https://github.com/jiwonme/noxion/blob/main/README.md

This command builds all packages within the Noxion project using the Bun runtime. It's a fundamental step for preparing the project for deployment or further development.

```shell
bun run build
```

--------------------------------

### Handling Empty State for PostList

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/renderer/post-list.md

Provides an example of how to conditionally render a message when the 'posts' array is empty. The PostList component itself renders nothing in this case, so the parent component must handle the empty state.

```tsx
{
  posts.length === 0 ? (
    <p>No posts published yet.</p>
  ) : (
    <PostList posts={posts} />
  )
}
```

--------------------------------

### Build and Run with Dockerfile

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/deployment/docker.md

This snippet shows how to build a custom Docker image for the Noxion web application using the provided Dockerfile and then run it. The Dockerfile utilizes a 3-stage build process (deps, build, runner) for an optimized production image. Environment variables can be passed via `-e` flags or a `.env` file.

```bash
# Build image
docker build -t my-blog ./apps/web

# Run
docker run -p 3000:3000 \
  -e NOTION_PAGE_ID=abc123 \
  -e SITE_NAME="My Blog" \
  -e SITE_DOMAIN=myblog.com \
  my-blog
```

--------------------------------

### Managing Theme Preference with useThemePreference Hook

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/renderer/theme-provider.md

The useThemePreference hook provides functionality to get and set the user's preferred theme mode. It returns the current mode ('light', 'dark', or 'system') and a function to update it.

```ts
import { useThemePreference } from "@noxion/renderer";

const { mode, setMode } = useThemePreference();

console.log(mode); // Outputs 'light', 'dark', or 'system'

// To change the mode:
setMode("dark");
```

--------------------------------

### Configure Noxion Blog Settings

Source: https://github.com/jiwonme/noxion/blob/main/README.md

This TypeScript configuration file demonstrates how to set up your Noxion blog. It includes essential settings like the Notion page ID, site metadata, and plugin configurations for RSS and analytics.

```typescript
// noxion.config.ts
import { defineConfig, createRSSPlugin, createAnalyticsPlugin } from "@noxion/core";

export default defineConfig({
  rootNotionPageId: process.env.NOTION_PAGE_ID!,
  name: "My Blog",
  domain: "myblog.com",
  author: "Your Name",
  description: "A blog about things I find interesting",
  language: "en",
  defaultTheme: "system",
  plugins: [
    createRSSPlugin({ feedPath: "/feed.xml", limit: 20 }),
    createAnalyticsPlugin({ provider: "google", trackingId: process.env.GA_ID }),
  ],
});
```

--------------------------------

### Run Tests with Bun

Source: https://github.com/jiwonme/noxion/blob/main/README.md

Executes all defined tests for the Noxion project using the Bun runtime. This command is crucial for ensuring the stability and correctness of the codebase.

```shell
bun run test
```

--------------------------------

### Fetch All Post Slugs for Static Site Generation

Source: https://context7.com/jiwonme/noxion/llms.txt

Fetches all post slugs from a Notion database, essential for static site generation (SSG) in Next.js using `generateStaticParams`. It requires a Notion client and the database ID.

```typescript
import { createNotionClient, fetchAllSlugs } from "@noxion/core";

// In Next.js App Router: app/[slug]/page.tsx
export async function generateStaticParams() {
  const client = createNotionClient();
  const databaseId = process.env.NOTION_PAGE_ID!;

  const slugs = await fetchAllSlugs(client, databaseId);

  // Returns: ["my-first-post", "second-post", "tutorial-react"]
  return slugs.map((slug) => ({ slug }));
}
```

--------------------------------

### @noxion/adapter-nextjs API

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/overview.md

Next.js SEO adapters for metadata, JSON-LD, and sitemaps.

```APIDOC
## Next.js Adapters

### `generateNoxionMetadata()`

#### Description
Generates post-level Next.js Metadata.

#### Method
`function`

#### Endpoint
N/A (Next.js integration function)

### `generateNoxionListMetadata()`

#### Description
Generates site-level Metadata for Next.js.

#### Method
`function`

#### Endpoint
N/A (Next.js integration function)

### `generateBlogPostingLD()`

#### Description
Generates BlogPosting JSON-LD for Next.js.

#### Method
`function`

#### Endpoint
N/A (Next.js integration function)

### `generateBreadcrumbLD()`

#### Description
Generates BreadcrumbList JSON-LD for Next.js.

#### Method
`function`

#### Endpoint
N/A (Next.js integration function)

### `generateNoxionSitemap()`

#### Description
Generates sitemap entries for Next.js.

#### Method
`function`

#### Endpoint
N/A (Next.js integration function)
```

--------------------------------

### Create Umami Analytics Plugin

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/plugins/analytics.md

Initializes the analytics plugin for Umami Analytics. Requires the website ID provided by Umami.

```typescript
createAnalyticsPlugin({
  provider: "umami",
  trackingId: "your-website-id",
})
```

--------------------------------

### Enable Build-time Image Download

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/image-optimization.md

Setting the `NOXION_DOWNLOAD_IMAGES` environment variable to `true` enables the download of images to the `public/images/` directory during production builds. This allows Next.js to serve images as static assets, removing runtime dependencies on external image proxies. This setting is ignored during development.

```bash
# .env
NOXION_DOWNLOAD_IMAGES=true
```

--------------------------------

### Create Plausible Analytics Plugin

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/plugins/analytics.md

Initializes the analytics plugin for Plausible Analytics. Requires the domain name as the tracking ID.

```typescript
createAnalyticsPlugin({
  provider: "plausible",
  trackingId: "yourdomain.com",
})
```

--------------------------------

### Fetch Notion Post by Slug for Dynamic Routing

Source: https://context7.com/jiwonme/noxion/llms.txt

Fetches a specific blog post by its slug, designed for dynamic routing in frameworks like Next.js. It requires a Notion client, database ID, and the post's slug, returning the full page content after finding the post.

```typescript
import { createNotionClient, fetchPostBySlug, fetchPage } from "@noxion/core";

// In a Next.js page component
export default async function PostPage({
  params,
}: {
  params: { slug: string };
}) {
  const client = createNotionClient();
  const databaseId = process.env.NOTION_PAGE_ID!;

  // Find the post by slug
  const post = await fetchPostBySlug(client, databaseId, params.slug);

  if (!post) {
    notFound();
  }

  // Fetch the full page content
  const recordMap = await fetchPage(client, post.id);

  return <NotionPage recordMap={recordMap} />;
}
```

--------------------------------

### Docker Deployment for Noxion Application

Source: https://context7.com/jiwonme/noxion/llms.txt

Provides a Dockerfile for containerized deployment of the Noxion application. It supports build-time image downloading and runtime environment configuration through environment variables.

```dockerfile
# Build the container
docker build -t noxion ./apps/web

# Run with environment variables
docker run -p 3000:3000 \
  -e NOTION_PAGE_ID=abc123-your-page-id \
  -e SITE_DOMAIN=myblog.com \
  -e SITE_NAME="My Blog" \
  -e SITE_AUTHOR="John Doe" \
  -e SITE_DESCRIPTION="A blog about tech" \
  -e NOXION_DOWNLOAD_IMAGES=true \
  noxion
```

```yaml
# docker-compose.yml
version: "3.8"
services:
  noxion:
    build: ./apps/web
    ports:
      - "3000:3000"
    environment:
      - NOTION_PAGE_ID=${NOTION_PAGE_ID}
      - NOTION_TOKEN=${NOTION_TOKEN}
      - SITE_DOMAIN=${SITE_DOMAIN}
      - SITE_NAME=${SITE_NAME}
      - REVALIDATE_SECRET=${REVALIDATE_SECRET}
    restart: unless-stopped
```

--------------------------------

### Configure Noxion Site Settings with defineConfig

Source: https://context7.com/jiwonme/noxion/llms.txt

The `defineConfig` function creates a type-safe configuration object for Noxion. It allows you to set site metadata, Notion connection details, and integrate optional plugins for analytics, RSS feeds, and comments. This configuration is essential for customizing your blog's appearance, behavior, and SEO settings.

```typescript
// noxion.config.ts
import {
  defineConfig,
  createRSSPlugin,
  createAnalyticsPlugin,
  createCommentsPlugin,
} from "@noxion/core";

export default defineConfig({
  // Required: Notion database page ID from URL
  rootNotionPageId: process.env.NOTION_PAGE_ID!,

  // Required: Site metadata
  name: "My Tech Blog",
  domain: "myblog.com",
  author: "John Doe",
  description: "Articles about web development and open source",

  // Optional: Defaults shown
  language: "en",
  defaultTheme: "system", // "light" | "dark" | "system"
  revalidate: 3600, // ISR revalidation in seconds

  // Optional: Secret for on-demand revalidation API
  revalidateSecret: process.env.REVALIDATE_SECRET,

  // Optional: Plugins
  plugins: [
    createRSSPlugin({
      feedPath: "/feed.xml",
      limit: 20,
    }),
    createAnalyticsPlugin({
      provider: "google", // "google" | "plausible" | "umami" | "custom"
      trackingId: process.env.NEXT_PUBLIC_GA_ID!,
    }),
    createCommentsPlugin({
      provider: "giscus",
      config: {
        repo: "username/repo",
        repoId: "R_kgDOxxxx",
        category: "Comments",
        categoryId: "DIC_kwDOxxxx",
        mapping: "pathname",
        theme: "preferred_color_scheme",
      },
    }),
  ],
});
```

--------------------------------

### Create Notion Client

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/core/fetcher.md

Initializes a Notion API client. An optional `authToken` can be provided for accessing private Notion pages. The client is essential for all subsequent data fetching operations.

```typescript
function createNotionClient(options: { authToken?: string }): NotionAPI
```

```typescript
const notion = createNotionClient({
  authToken: process.env.NOTION_TOKEN,
});
```

--------------------------------

### generateWebSiteLD

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/adapter-nextjs/structured-data.md

Generates a WebSite JSON-LD object for the homepage. It includes a SearchAction for the Google Sitelinks Search Box.

```APIDOC
## `generateWebSiteLD()`

### Description
Generates a `WebSite` JSON-LD for the homepage, including a `SearchAction` for Google Sitelinks Search Box.

### Method
```ts
function generateWebSiteLD(config: NoxionConfig): JsonLd
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **config** (NoxionConfig) - Required - The site configuration.

### Request Example
```json
{
  "config": { ... }
}
```

### Response
#### Success Response (200)
- **JsonLd** - The generated JSON-LD object for WebSite.

#### Response Example
```json
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://example.com/",
  "name": "Site Name",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://example.com/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}
```
```

--------------------------------

### Fetch All Blog Posts

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/core/fetcher.md

Retrieves all published blog posts from a specified Notion database. It fetches collection data, filters by public status, maps Notion properties to a `BlogPost` structure, parses frontmatter, and sorts the posts by date in descending order.

```typescript
async function fetchBlogPosts(
  client: NotionAPI,
  rootPageId: string
): Promise<BlogPost[]>
```

--------------------------------

### Create Google Analytics Plugin

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/plugins/analytics.md

Initializes the analytics plugin for Google Analytics. Requires a tracking ID, typically fetched from environment variables.

```typescript
createAnalyticsPlugin({
  provider: "google",
  trackingId: process.env.NEXT_PUBLIC_GA_ID, // "G-XXXXXXXXXX"
})
```

--------------------------------

### Display Blog Posts with PostList and PostCard Components

Source: https://context7.com/jiwonme/noxion/llms.txt

These React components, `PostList` and `PostCard` from '@noxion/renderer', are used to display a grid of blog posts. `PostList` renders a responsive grid of `PostCard` components, while `PostCard` displays individual post details like title, date, tags, and cover image. They utilize data fetched using `fetchBlogPosts` from '@noxion/core'.

```tsx
import { PostList, PostCard } from "@noxion/renderer";
import { fetchBlogPosts, createNotionClient } from "@noxion/core";

// PostList renders a responsive grid of PostCards
export default async function HomePage() {
  const client = createNotionClient();
  const posts = await fetchBlogPosts(client, process.env.NOTION_PAGE_ID!);

  return (
    <main>
      <h1>Latest Posts</h1>
      <PostList posts={posts} />
    </main>
  );
}

// Use PostCard individually for custom layouts
export function FeaturedPost({ post }) {
  return (
    <article className="featured">
      <PostCard
        id={post.id}
        title={post.title}
        slug={post.slug}
        date={post.date}
        tags={post.tags}
        category={post.category}
        coverImage={post.coverImage}
      />
    </article>
  );
}

// PostCard renders:
// - Cover image (or gradient placeholder)
// - Category badge
// - Title
// - Date
// - Tag pills
// Styled with CSS variables: --noxion-primary, --noxion-card, --noxion-border, etc.
```

--------------------------------

### Fetch Blog Post by Slug

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/core/fetcher.md

Fetches all published blog posts and then identifies and returns the specific post that matches the provided slug. If no post is found with the given slug, it returns `undefined`.

```typescript
async function fetchPostBySlug(
  client: NotionAPI,
  rootPageId: string,
  slug: string
): Promise<BlogPost | undefined>
```

--------------------------------

### @noxion/renderer API

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/overview.md

React components for rendering Notion content.

```APIDOC
## Renderer Components

### `<NotionPage />`

#### Description
Component to render a Notion page.

#### Method
`React Component`

#### Endpoint
N/A (Client-side component)

### `<PostList />`

#### Description
Component to render a list of post cards.

#### Method
`React Component`

#### Endpoint
N/A (Client-side component)

### `<PostCard />`

#### Description
Component to render a single post card.

#### Method
`React Component`

#### Endpoint
N/A (Client-side component)

### `<NoxionThemeProvider />`

#### Description
Theme context provider for Noxion components.

#### Method
`React Component`

#### Endpoint
N/A (Client-side component)
```

--------------------------------

### NotionPage Component Usage

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/renderer/notion-page.md

Demonstrates how to import and use the NotionPage component, including basic props and image optimization with Next.js.

```APIDOC
## NotionPage Component

### Description
Renders a Notion page using `react-notion-x`. This is a client component and requires the `"use client"` directive.

### Method
Component

### Endpoint
N/A (Component)

### Parameters
#### Props
- **recordMap** (`ExtendedRecordMap`) - Required - Page data fetched from `fetchPage()`.
- **rootPageId** (`string`) - Optional - The root page ID used for resolving internal links.
- **fullPage** (`boolean`) - Optional - Defaults to `true`. Determines if the page should be rendered as a full page with a header.
- **darkMode** (`boolean`) - Optional - Forces dark mode. If not provided, it auto-detects from the theme.
- **previewImages** (`boolean`) - Optional - Defaults to `false`. Enables image previews.
- **showTableOfContents** (`boolean`) - Optional - Defaults to `false`. Displays the table of contents sidebar.
- **minTableOfContentsItems** (`number`) - Optional - Defaults to `3`. The minimum number of items required before the TOC renders.
- **pageUrlPrefix** (`string`) - Optional - Defaults to `"/"`. A prefix to be added to internal page links.
- **nextImage** (`unknown`) - Optional - Allows passing the `next/image` component for image optimization.
- **className** (`string`) - Optional - A CSS class to be applied to the wrapper div.

### Request Example
```tsx
import { NotionPage } from "@noxion/renderer";

// Assuming recordMap and post.id are defined elsewhere
<NotionPage
  recordMap={recordMap}
  rootPageId={post.id}
  fullPage={true}
  darkMode={false}
  previewImages={true}
  showTableOfContents={true}
  minTableOfContentsItems={5}
  pageUrlPrefix="/docs/"
/>;
```

### Image Optimization Example
```tsx
import Image from "next/image";
import { NotionPage } from "@noxion/renderer";

// Assuming recordMap and post.id are defined elsewhere
<NotionPage
  recordMap={recordMap}
  rootPageId={post.id}
  nextImage={Image} 
/>;
```

### Response
#### Success Response (Rendered Component)
- The component renders the Notion page content based on the provided `recordMap` and props.

#### Response Example
(This is a component, not a direct API response. The output is rendered HTML/UI.)
```

--------------------------------

### Create a Notion API Client with createNotionClient

Source: https://context7.com/jiwonme/noxion/llms.txt

The `createNotionClient` function generates an instance of the Notion API client. This client is used for fetching data from your Notion database. It supports both public pages (without authentication) and private pages by accepting an optional `authToken` for Notion integration tokens.

```typescript
import { createNotionClient } from "@noxion/core";

// Public pages (no auth required)
const client = createNotionClient();

// Private pages (requires Notion integration token)
const privateClient = createNotionClient({
  authToken: process.env.NOTION_TOKEN,
});

// The client is used with fetcher functions
const recordMap = await fetchPage(client, "abc123-page-id");
```

--------------------------------

### generateBlogPostingLD

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/adapter-nextjs/structured-data.md

Generates a BlogPosting JSON-LD object for a post page. This object includes details like headline, description, dates, author, publisher, image, keywords, and more.

```APIDOC
## `generateBlogPostingLD()`

### Description
Generates a `BlogPosting` JSON-LD object for a post page.

### Method
```ts
function generateBlogPostingLD(post: BlogPost, config: NoxionConfig): JsonLd
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **post** (BlogPost) - Required - The blog post data.
- **config** (NoxionConfig) - Required - The site configuration.

### Request Example
```json
{
  "post": { ... },
  "config": { ... }
}
```

### Response
#### Success Response (200)
- **JsonLd** - The generated JSON-LD object for BlogPosting.

#### Response Example
```json
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Example Post Title",
  "description": "This is an example blog post.",
  "datePublished": "2023-01-01",
  "dateModified": "2023-01-01",
  "author": {
    "@type": "Person",
    "name": "Author Name"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Site Name",
    "logo": {
      "@type": "ImageObject",
      "url": "/logo.png"
    }
  },
  "image": {
    "@type": "ImageObject",
    "url": "/post-image.jpg"
  },
  "keywords": "example, post, seo",
  "articleSection": "Technology",
  "inLanguage": "en-US",
  "isAccessibleForFree": true
}
```
```

--------------------------------

### Create an RSS Feed Plugin with createRSSPlugin()

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/core/plugins.md

Generates an RSS feed for a Noxion site. The `createRSSPlugin` function requires a `feedPath` (e.g., '/feed.xml') to specify the URL of the feed. An optional `limit` parameter can be set to control the number of posts included in the feed, defaulting to 20.

```typescript
createRSSPlugin({
  feedPath: string,  // e.g. "/feed.xml"
  limit?: number,    // default: 20
})
```

--------------------------------

### robots.txt Configuration

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/seo.md

Provides the content of the robots.txt file for search engine crawling instructions.

```APIDOC
## robots.txt Configuration

### Description
Provides the content of the robots.txt file, which instructs search engine crawlers on which pages to access or avoid.

### Method
N/A (Informational)

### Endpoint
`/robots.txt`

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
```
User-agent: *
Allow: /
Disallow: /api/
Disallow: /_next/

Sitemap: https://yourdomain.com/sitemap.xml
Host: https://yourdomain.com
```

#### Response Example
N/A
```

--------------------------------

### Generate BlogPosting JSON-LD

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/adapter-nextjs/structured-data.md

Generates a `BlogPosting` JSON-LD object for a post page. It includes details like headline, description, dates, author, publisher, image, keywords, and more. Requires a BlogPost object and NoxionConfig.

```typescript
function generateBlogPostingLD(post: BlogPost, config: NoxionConfig): JsonLd
```

--------------------------------

### Generate WebSite JSON-LD

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/adapter-nextjs/structured-data.md

Generates a `WebSite` JSON-LD object for the homepage. This includes a `SearchAction` designed for Google Sitelinks Search Box integration. Requires NoxionConfig.

```typescript
function generateWebSiteLD(config: NoxionConfig): JsonLd
```

--------------------------------

### Add Plugins to Noxion Configuration (TypeScript)

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/plugins/overview.md

Demonstrates how to configure Noxion to use built-in plugins like RSS and Analytics by importing necessary functions from '@noxion/core' and defining them in the 'noxion.config.ts' file.

```typescript
import { defineConfig, createRSSPlugin, createAnalyticsPlugin } from "@noxion/core";

export default defineConfig({
  plugins: [
    createRSSPlugin({ feedPath: "/feed.xml" }),
    createAnalyticsPlugin({ provider: "google", trackingId: "G-XXXXXXXXXX" }),
  ],
});
```

--------------------------------

### Fetch Blog Posts from Notion with fetchBlogPosts

Source: https://context7.com/jiwonme/noxion/llms.txt

The `fetchBlogPosts` function retrieves all published blog posts from a specified Notion database. It automatically parses the database schema to extract essential metadata such as title, slug, date, tags, category, cover image, and publication status. The fetched posts can be filtered or sliced for use in various parts of your blog, like the homepage or category pages.

```typescript
import { createNotionClient, fetchBlogPosts } from "@noxion/core";

const client = createNotionClient();
const databasePageId = process.env.NOTION_PAGE_ID!;

// Fetch all published posts sorted by date (newest first)
const posts = await fetchBlogPosts(client, databasePageId);

// Each post contains:
// {
//   id: "abc123",
//   title: "My First Post",
//   slug: "my-first-post",
//   date: "2024-01-15",
//   tags: ["javascript", "react"],
//   category: "Tutorial",
//   description: "Learn how to build...",
//   author: "John Doe",
//   coverImage: "https://notion.so/image/...",
//   published: true,
//   lastEditedTime: "2024-01-15T10:30:00.000Z",
//   frontmatter: { cleanUrl: "/custom-slug" }
// }

// Filter posts by tag
const reactPosts = posts.filter((post) => post.tags.includes("react"));

// Get recent posts for homepage
const recentPosts = posts.slice(0, 10);
```

--------------------------------

### Create RSS Plugin Configuration

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/plugins/rss.md

Configures the RSS Plugin with a specified feed path and a limit for the number of posts included in the feed. This function is essential for setting up the RSS feed generation.

```typescript
createRSSPlugin({
  feedPath: "/feed.xml",  // URL path for the feed
  limit: 20,              // Max posts in feed
})
```

--------------------------------

### Define Custom Noxion Plugin Lifecycle Hooks (TypeScript)

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/plugins/overview.md

Shows how to create a custom plugin using the 'definePlugin' function from '@noxion/core'. It illustrates implementing lifecycle hooks like 'onPostFetch' to modify posts and 'onHeadTags' to inject custom head elements.

```typescript
import { definePlugin } from "@noxion/core";

export const myPlugin = definePlugin({
  name: "my-plugin",
  async onPostFetch(posts) {
    // Transform posts after fetching
    return posts.map(post => ({ ...post, title: post.title.toUpperCase() }));
  },
  async onHeadTags(post) {
    // Inject custom <head> tags per post
    return [{ tagName: "meta", attributes: { name: "custom", content: "value" } }];
  },
});
```

--------------------------------

### Define Noxion Configuration with Plugins (TypeScript)

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/configuration.md

This snippet demonstrates how to define the Noxion configuration using `defineConfig`. It includes essential site metadata, theme settings, and integrates several plugins: RSS feed generation, Google Analytics, and Giscus comments. Environment variables are used for sensitive information and external service IDs.

```typescript
import {
  defineConfig,
  createRSSPlugin,
  createAnalyticsPlugin,
  createCommentsPlugin,
} from "@noxion/core";

export default defineConfig({
  rootNotionPageId: process.env.NOTION_PAGE_ID!,
  rootNotionSpaceId: process.env.NOTION_SPACE_ID,

  name: "My Blog",
  domain: "myblog.com",
  author: "Your Name",
  description: "A blog about things I find interesting",
  language: "ko",           // Used for <html lang> and og:locale
  defaultTheme: "system",   // "light" | "dark" | "system"
  revalidate: 3600,         // ISR revalidation interval in seconds
  revalidateSecret: process.env.REVALIDATE_SECRET,

  plugins: [
    createRSSPlugin({
      feedPath: "/feed.xml",
      limit: 20,
    }),
    createAnalyticsPlugin({
      provider: "google",
      trackingId: process.env.NEXT_PUBLIC_GA_ID,
    }),
    createCommentsPlugin({
      provider: "giscus",
      config: {
        repo: process.env.NEXT_PUBLIC_GISCUS_REPO,
        repoId: process.env.NEXT_PUBLIC_GISCUS_REPO_ID,
        category: "Announcements",
        categoryId: process.env.NEXT_PUBLIC_GISCUS_CATEGORY_ID,
      },
    }),
  ],
});
```

--------------------------------

### Create an Analytics Plugin with createAnalyticsPlugin()

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/core/plugins.md

Creates an analytics plugin for Noxion. This factory function supports multiple providers like 'google', 'plausible', 'umami', or a 'custom' option. It requires a `trackingId` and optionally accepts a `customScript` for the 'custom' provider. This plugin helps integrate website analytics into the Noxion project.

```typescript
createAnalyticsPlugin({
  provider: "google" | "plausible" | "umami" | "custom",
  trackingId: string,
  customScript?: string,  // for "custom" provider
})
```

--------------------------------

### BlogPost Interface Definition

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/core/types.md

Defines the structure for a blog post, including its ID, title, slug, date, tags, category, cover image, description, author, publication status, last edited time, and optional frontmatter.

```typescript
interface BlogPost {
  id: string;              // Notion page ID (UUID)
  title: string;
  slug: string;            // URL slug
  date: string;            // ISO date string
  tags: string[];
  category?: string;
  coverImage?: string;     // notion.so/image/... proxy URL
  description?: string;
  author?: string;
  published: boolean;
  lastEditedTime: string;  // ISO datetime string
  frontmatter?: Record<string, string>;
}
```

--------------------------------

### Configure Next.js Image for Notion Proxy

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/image-optimization.md

This configuration snippet for `next.config.ts` enables Next.js Image optimization for Notion images. It sets supported formats to AVIF and WebP and configures remote patterns to allow requests to Notion's image domains. This is automatically set up by `create-noxion`.

```typescript
images: {
  formats: ["image/avif", "image/webp"],
  remotePatterns: [
    { protocol: "https", hostname: "www.notion.so" },
    { protocol: "https", hostname: "file.notion.so" },
    // ...
  ],
}
```

--------------------------------

### Create Analytics Tracking Plugin

Source: https://context7.com/jiwonme/noxion/llms.txt

Creates a plugin to inject analytics tracking scripts into the page head. It supports Google Analytics, Plausible, Umami, and custom script URLs, configured via a provider and tracking ID.

```typescript
import { createAnalyticsPlugin } from "@noxion/core";

// Google Analytics
const googleAnalytics = createAnalyticsPlugin({
  provider: "google",
  trackingId: "G-XXXXXXXXXX",
});

// Plausible Analytics (privacy-focused)
const plausible = createAnalyticsPlugin({
  provider: "plausible",
  trackingId: "myblog.com", // Your domain
});

// Umami Analytics (self-hosted)
const umami = createAnalyticsPlugin({
  provider: "umami",
  trackingId: "website-id-uuid",
});

// Custom analytics script
const custom = createAnalyticsPlugin({
  provider: "custom",
  trackingId: "",
  customScript: "https://analytics.example.com/tracker.js",
});

// Use in config
export default defineConfig({
  // ...
  plugins: [googleAnalytics],
});
```

--------------------------------

### Create a Comments Plugin with createCommentsPlugin()

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/core/plugins.md

Integrates a comments system into a Noxion site. This factory supports providers like 'giscus', 'utterances', and 'disqus'. It requires a `config` object specific to the chosen provider, allowing for detailed customization of the comment section.

```typescript
createCommentsPlugin({
  provider: "giscus" | "utterances" | "disqus",
  config: GiscusConfig | UtterancesConfig | DisqusConfig,
})
```

--------------------------------

### generateCollectionPageLD

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/adapter-nextjs/structured-data.md

Generates a CollectionPage JSON-LD object with an ItemList of posts, suitable for the homepage. It includes up to 30 posts.

```APIDOC
## `generateCollectionPageLD()`

### Description
Generates a `CollectionPage` with `ItemList` of posts for the homepage.

### Method
```ts
function generateCollectionPageLD(posts: BlogPost[], config: NoxionConfig): JsonLd
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **posts** (BlogPost[]) - Required - An array of blog post data (up to 30).
- **config** (NoxionConfig) - Required - The site configuration.

### Request Example
```json
{
  "posts": [ { ... }, { ... } ],
  "config": { ... }
}
```

### Response
#### Success Response (200)
- **JsonLd** - The generated JSON-LD object for CollectionPage.

#### Response Example
```json
{
  "@context": "https://schema.org",
  "@type": "CollectionPage",
  "name": "Homepage",
  "description": "Latest posts from the blog",
  "url": "https://example.com/",
  "mainContentOfPage": {
    "@type": "ItemList",
    "numberOfItems": 30,
    "itemListElement": [
      {
        "@type": "ListItem",
        "position": 1,
        "item": {
          "@type": "BlogPosting",
          "headline": "Post 1 Title",
          "url": "https://example.com/post-1"
        }
      },
      {
        "@type": "ListItem",
        "position": 2,
        "item": {
          "@type": "BlogPosting",
          "headline": "Post 2 Title",
          "url": "https://example.com/post-2"
        }
      }
      // ... up to 30 items
    ]
  }
}
```
```

--------------------------------

### Vercel Environment Variables for Manual Deploy

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/learn/deployment/vercel.md

These are the essential environment variables required for a manual deployment of the Noxion project to Vercel. They configure the Notion integration, site metadata, and author information.

```env
NOTION_PAGE_ID=your-page-id
SITE_NAME=My Blog
SITE_DOMAIN=myblog.vercel.app
SITE_AUTHOR=Your Name
SITE_DESCRIPTION=My blog description
```

--------------------------------

### defineConfig

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/core/config.md

Creates a NoxionConfig object with defaults applied. This function is used to configure your Noxion project.

```APIDOC
## defineConfig

### Description
Creates a `NoxionConfig` object with defaults applied.

### Method
N/A (This is a utility function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
##### `NoxionConfigInput`
- **rootNotionPageId** (string) - Required - Root Notion database page ID
- **name** (string) - Required - Site name
- **domain** (string) - Required - Production domain (no protocol)
- **author** (string) - Required - Default author name
- **description** (string) - Required - Site description
- **rootNotionSpaceId** (string) - Optional - Notion workspace ID
- **language** (string) - Optional - Site language code (defaults to "en")
- **defaultTheme** (ThemeMode) - Optional - Default color scheme (defaults to "system")
- **revalidate** (number) - Optional - ISR revalidation interval in seconds (defaults to 3600)
- **revalidateSecret** (string) - Optional - Secret for on-demand revalidation
- **plugins** (PluginConfig[]) - Optional - Plugins to enable (defaults to [])

### Request Example
```ts
import { defineConfig } from "@noxion/core";

export default defineConfig({
  rootNotionPageId: process.env.NOTION_PAGE_ID!,
  name: "My Blog",
  domain: "myblog.com",
  author: "Your Name",
  description: "A blog about things",
  language: "ko",
  defaultTheme: "system",
  revalidate: 3600,
});
```

### Response
#### Success Response (200)
`NoxionConfig` - normalized config with all defaults applied.

#### Response Example
(This function returns a configuration object, not a typical API response.)
```

--------------------------------

### Generate CollectionPage JSON-LD

Source: https://github.com/jiwonme/noxion/blob/main/apps/docs/docs/reference/adapter-nextjs/structured-data.md

Generates a `CollectionPage` JSON-LD with an `ItemList` of posts, suitable for the homepage. It can include up to 30 posts as `ListItem` entries. Requires an array of BlogPost objects and NoxionConfig.

```typescript
function generateCollectionPageLD(posts: BlogPost[], config: NoxionConfig): JsonLd
```