DOCSEARCHbyAlgolia
Submit Docs

NotionNext

repository·main·Indexed 11 days ago

https://github.com/notionnext-org/notionnext

An open-source website builder that turns Notion pages into high-performance, customizable websites such as blogs, portfolios, and documentation sites using Next.js. Version 4.10.9 includes features for custom theme development, a Notion image proxy for Cloudflare Workers, and deployment guides for Vercel.

Tokens
217K
Snippets
536
Records
1.1K
Agent score
95%

What's inside NotionNext

  1. Overview of the Magzine Theme

    main

    The Magzine theme is a minimalist, flat, and professional theme for NotionNext. It organizes articles by category on the homepage for clearer logical flow.

    Homepage Layout

    • Hero Section: The first article in Notion is featured prominently in the top-left. The top-right features a configurable banner/promotion area. The second and third articles are displayed below the banner.
    • Latest Articles: Displays up to 4 recent articles (excluding those in the hero section). A 'View All' link leads to the archive.
    • Category Sections: Groups articles by category, displaying one row per category.
    • Recommended Articles: Displays articles with a specific tag (default is 推荐). This section can be customized via configuration.
    • Announcements: Displays notices edited in Notion using the Notice block.
    • Footer: Contains author info, site title, and custom grouped navigation menus.

    Article Detail Page Layout

    • Top Section: Displays category tags, title, summary, and cover image.
    • Main Content: Features the article body, a left-side table of contents, a right-side publication date, and a 'Recently Updated' list (sorted by modification time).
    • Bottom Section: Includes category navigation, a social/community card, and a promotion banner.

  2. Overview of NotionComments

    main

    NotionComments is a plugin for NotionNext that uses a standalone Notion database to store and manage site comments. It is designed for users who want to avoid deploying external comment backends like Twikoo or Waline.

    Key Characteristics:

    • No Notion Login Required: Visitors only need to provide an email and comment content; they do not need a Notion account.
    • Standalone Database: Unlike Notion's native page comments, this uses a dedicated database, providing better control over permissions and data.
    • Deployment Requirement: It relies on the /api/notion-comments server-side endpoint. It cannot be used with purely static sites generated via yarn export. It requires dynamic hosting such as Vercel, Netlify, Zeabur, or a VPS.

  3. What is NotionNext

    main

    NotionNext is an open-source website building system based on Notion and Next.js. It uses Notion as a content source (CMS) and Next.js as the presentation layer.

    Core Workflow:

    1. Write & Manage: You create and organize content (articles, categories, tags, covers, etc.) directly in Notion.
    2. Render: NotionNext fetches this data from your Notion database and renders it into a high-performance, SEO-friendly website.
    3. Deploy: The site can be deployed to platforms like Vercel, Cloudflare Pages, or a VPS.

    This architecture allows you to maintain a professional website without managing a complex backend database, as Notion serves as your database.

  4. Key features of the Endspace theme

    main

    The Endspace theme provides an industrial sci-fi aesthetic inspired by Arknights: Endfield. Key technical features include:

    • Layout: Desktop uses a side rail navigation, while mobile uses bottom navigation. Includes an integrated music player widget.
    • Article Structure: Article pages wrap the NotionPage component inside an #article-wrapper element.
    • Animations: Supports an optional NEST animation. The mount point for the animation script (public/js/nest.js) is #__nest. In this implementation, attributes are set via ref and useEffect to ensure React DOM compatibility.

  5. Understand the NotionNext project structure

    main

    NotionNext is organized into several key directories that separate routing, UI themes, core logic, and configuration. Understanding this structure is essential for knowing where to implement changes.

    Core Directories

    • pages/: The entry point for Next.js routing. This is where SSG (Static Site Generation) and ISR (Incremental Static Regeneration) logic like getStaticProps and getStaticPaths resides.
    • themes/: Contains the implementation for different themes, including UI components and theme-specific configurations.
    • components/: Houses reusable components that are shared across multiple themes.
    • lib/: The core logic layer, including data fetching, caching, utility functions, and configuration reading.
    • conf/: Contains split configuration files which are aggregated by blog.config.js.
    • __tests__/: Contains unit tests.
    • scripts/: Engineering scripts for quality checks, initialization, and git hooks.
    • .github/: Contains Issue/PR templates and collaboration metadata.

  8. Access NotionNext Developer Documentation

    main

    The developer documentation is distinct from the user-facing site (notionnext.tangly1024.com). Use this directory to access technical guides for contributing to the core project, understanding the architecture, and developing custom themes.

    Key documentation areas:

    • Getting Started: Quickstart guides for developers.
    • Architecture & Structure: Overviews of the system design, module organization, and configuration systems.
    • Theme Development: Specific documentation for building and migrating themes.
    • Contribution: Workflows for submitting Pull Requests (PRs) and project governance.

  9. ThoughtLite Theme Overview and Features

    main

    ThoughtLite is a reading-focused, lightweight theme for NotionNext inspired by the Astro-based ThoughtLite theme. It uses a timeline-style homepage and minimal navigation.

    Key Features:

    • Header: Site title, horizontal navigation (custom menus), search entry, and dark/light mode toggle.
    • Homepage: Supports a 'Latest' summary card and a timeline list grouped by publishDay.
    • Post Pages: Features a card-style title area, PostMeta, NotionPage content, ShareBar, and a sidebar (TOC).
    • Specialized Pages: Unified TlPageHero header for Archives, Categories, Tags, and Search. Archives use a timeline sidebar, while Categories and Tags use tl-chip styling.
    • Footer: Includes copyright, registration info, and attribution to the original ThoughtLite project.

  11. Locate NotionNext documentation and guides

    main

    As of 2026, the authoritative source for NotionNext documentation is the docs/ directory within this repository. This replaces the legacy Notion-hosted documentation. Documentation is split into two main categories based on your needs:

    • User Guides (docs/user-guide/): For deployment, configuration, Notion database setup, menu management, and upgrades.
    • Reference Manual (docs/user-guide/reference/): A complete index of site configurations and Notion capabilities (kept in sync with conf/).
    • Theme Catalog (docs/user-guide/themes/THEMES_CATALOG.md): A full list and selection guide for the 26 built-in themes.
    • Developer Documentation (docs/developer/): For architecture, contribution workflows, maintenance, theme migration, and RFCs.
    • Theme Implementation (docs/developer/themes/): Detailed guides on theme implementation, migration plans, and licensing.

  12. Overview of documentation structure

    main

    The documentation is organized into several key directories to support both end-users and developers:

    • user-guide/: Contains tutorials for deployment, configuration, themes, and operational maintenance.
    • developer/: Contains technical documentation regarding architecture, contributing, and theme migration/maintenance.
    • community/: Contains materials regarding community activities and discussions.
    • index.md & DOCUMENTATION_POLICY.md: The homepage and the documentation maintenance policy.