+ {renderList && (
+
setShow(false)}
+ />
+ )}
+
+
{
+ const { value } = e.target
+ onChange(value)
+ setShow(Boolean(value))
+ }}
+ onFocus={() => {
+ onActive?.(true)
+ setFocused(true)
+ }}
+ onBlur={() => {
+ setFocused(false)
+ }}
+ onCompositionStart={handleComposition}
+ onCompositionEnd={handleComposition}
+ type="search"
+ placeholder={renderString(config.search.placeholder)}
+ onKeyDown={handleKeyDown}
+ suffix={icon}
+ />
+
+
+
+ {error ? (
+
+
+ {renderString(config.search.error)}
+
+ ) : loading ? (
+
+
+ {renderComponent(config.search.loading)}
+
+ ) : results.length > 0 ? (
+ results.map(({ route, prefix, children, id }, i) => (
+
+ {prefix}
+ -
+
+ {children}
+
+
+
+ ))
+ ) : (
+ renderComponent(config.search.emptyResult)
+ )}
+
+
+
+ )
+}
diff --git a/theme/src/components/select.tsx b/theme/src/components/select.tsx
new file mode 100644
index 0000000..23a7dae
--- /dev/null
+++ b/theme/src/components/select.tsx
@@ -0,0 +1,105 @@
+import { Listbox, Transition } from '@headlessui/react'
+import cn from 'clsx'
+import { useMounted } from 'nextra/hooks'
+import { CheckIcon } from 'nextra/icons'
+import type { ReactElement, ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import { usePopper } from '../utils'
+
+interface MenuOption {
+ key: string
+ name: ReactElement | string
+}
+
+interface MenuProps {
+ selected: MenuOption
+ onChange: (option: MenuOption) => void
+ options: MenuOption[]
+ title?: string
+ className?: string
+}
+
+export function Select({
+ options,
+ selected,
+ onChange,
+ title,
+ className
+}: MenuProps): ReactElement {
+ const [trigger, container] = usePopper({
+ strategy: 'fixed',
+ placement: 'top-start',
+ modifiers: [
+ { name: 'offset', options: { offset: [0, 10] } },
+ {
+ name: 'sameWidth',
+ enabled: true,
+ fn({ state }) {
+ state.styles.popper.minWidth = `${state.rects.reference.width}px`
+ },
+ phase: 'beforeWrite',
+ requires: ['computeStyles']
+ }
+ ]
+ })
+
+ return (
+
+ {({ open }) => (
+
+ {selected.name}
+
+
+ {options.map(option => (
+
+ cn(
+ active
+ ? 'nx-bg-primary-50 nx-text-primary-600 dark:nx-bg-primary-500/10'
+ : 'nx-text-gray-800 dark:nx-text-gray-100',
+ 'nx-relative nx-cursor-pointer nx-whitespace-nowrap nx-py-1.5',
+ 'nx-transition-colors ltr:nx-pl-3 ltr:nx-pr-9 rtl:nx-pr-3 rtl:nx-pl-9'
+ )
+ }
+ >
+ {option.name}
+ {option.key === selected.key && (
+
+
+
+ )}
+
+ ))}
+
+
+
+ )}
+
+ )
+}
+
+function Portal(props: { children: ReactNode }): ReactElement | null {
+ const mounted = useMounted()
+ if (!mounted) return null
+ return createPortal(props.children, document.body)
+}
diff --git a/theme/src/components/sidebar.tsx b/theme/src/components/sidebar.tsx
new file mode 100644
index 0000000..cacd28e
--- /dev/null
+++ b/theme/src/components/sidebar.tsx
@@ -0,0 +1,527 @@
+import cn from 'clsx'
+import { useRouter } from 'next/router'
+import type { Heading } from 'nextra'
+import { useFSRoute, useMounted } from 'nextra/hooks'
+import { ArrowRightIcon, ExpandIcon } from 'nextra/icons'
+import type { Item, MenuItem, PageItem } from 'nextra/normalize-pages'
+import type { ReactElement } from 'react'
+import {
+ createContext,
+ memo,
+ useContext,
+ useEffect,
+ useMemo,
+ useRef,
+ useState
+} from 'react'
+import scrollIntoView from 'scroll-into-view-if-needed'
+import { useActiveAnchor, useConfig, useMenu } from '../contexts'
+import { renderComponent } from '../utils'
+import { Anchor } from './anchor'
+import { Collapse } from './collapse'
+import { LocaleSwitch } from './locale-switch'
+import { ExtendedItem, ExtendedPageItem } from '../types'
+import { useSession } from 'next-auth/react'
+import { shouldLinkBeRenderedAccordingToUserRole } from '../utils/render';
+
+const TreeState: Record
= Object.create(null)
+
+const FocusedItemContext = createContext(null)
+const OnFocusItemContext = createContext any)>(
+ null
+)
+const FolderLevelContext = createContext(0)
+
+const Folder = memo(function FolderInner(props: FolderProps) {
+ const level = useContext(FolderLevelContext)
+ return (
+
+
+
+ )
+})
+
+const classes = {
+ link: cn(
+ 'nx-flex nx-rounded nx-px-2 nx-py-1.5 nx-text-sm nx-transition-colors [word-break:break-word]',
+ 'nx-cursor-pointer [-webkit-tap-highlight-color:transparent] [-webkit-touch-callout:none] contrast-more:nx-border'
+ ),
+ inactive: cn(
+ 'nx-text-gray-500 hover:nx-bg-gray-100 hover:nx-text-gray-900',
+ 'dark:nx-text-neutral-400 dark:hover:nx-bg-primary-100/5 dark:hover:nx-text-gray-50',
+ 'contrast-more:nx-text-gray-900 contrast-more:dark:nx-text-gray-50',
+ 'contrast-more:nx-border-transparent contrast-more:hover:nx-border-gray-900 contrast-more:dark:hover:nx-border-gray-50'
+ ),
+ active: cn(
+ 'nx-bg-primary-100 nx-font-semibold nx-text-primary-800 dark:nx-bg-primary-400/10 dark:nx-text-primary-600',
+ 'contrast-more:nx-border-primary-500 contrast-more:dark:nx-border-primary-500'
+ ),
+ list: cn('nx-flex nx-flex-col nx-gap-1'),
+ border: cn(
+ 'nx-relative before:nx-absolute before:nx-inset-y-1',
+ 'before:nx-w-px before:nx-bg-gray-200 before:nx-content-[""] dark:before:nx-bg-neutral-800',
+ 'ltr:nx-pl-3 ltr:before:nx-left-0 rtl:nx-pr-3 rtl:before:nx-right-0'
+ )
+}
+
+type FolderProps = {
+ item: PageItem | MenuItem | Item
+ anchors: Heading[]
+}
+
+function FolderImpl({ item, anchors }: FolderProps): ReactElement {
+ const routeOriginal = useFSRoute()
+ const [route] = routeOriginal.split('#')
+ const active = [route, route + '/'].includes(item.route + '/')
+ const activeRouteInside = active || route.startsWith(item.route + '/')
+
+ const focusedRoute = useContext(FocusedItemContext)
+ const focusedRouteInside = !!focusedRoute?.startsWith(item.route + '/')
+ const level = useContext(FolderLevelContext)
+
+ const { setMenu } = useMenu()
+ const config = useConfig()
+ const { theme } = item as Item
+ const open =
+ TreeState[item.route] === undefined
+ ? active ||
+ activeRouteInside ||
+ focusedRouteInside ||
+ (theme && 'collapsed' in theme
+ ? !theme.collapsed
+ : level < config.sidebar.defaultMenuCollapseLevel)
+ : TreeState[item.route] || focusedRouteInside
+
+ const rerender = useState({})[1]
+
+ useEffect(() => {
+ const updateTreeState = () => {
+ if (activeRouteInside || focusedRouteInside) {
+ TreeState[item.route] = true
+ }
+ }
+ const updateAndPruneTreeState = () => {
+ if (activeRouteInside && focusedRouteInside) {
+ TreeState[item.route] = true
+ } else {
+ delete TreeState[item.route]
+ }
+ }
+ config.sidebar.autoCollapse ? updateAndPruneTreeState() : updateTreeState()
+ }, [
+ activeRouteInside,
+ focusedRouteInside,
+ item.route,
+ config.sidebar.autoCollapse
+ ])
+
+ if (item.type === 'menu') {
+ const menu = item as MenuItem
+ const routes = Object.fromEntries(
+ (menu.children || []).map(route => [route.name, route])
+ )
+ item.children = Object.entries(menu.items || {}).map(([key, item]) => {
+ const route = routes[key] || {
+ name: key,
+ ...('locale' in menu && { locale: menu.locale }),
+ route: menu.route + '/' + key
+ }
+ return {
+ ...route,
+ ...item
+ }
+ })
+ }
+
+ const isLink = 'withIndexPage' in item && item.withIndexPage
+ // use button when link don't have href because it impacts on SEO
+ const ComponentToUse = isLink ? Anchor : 'button'
+
+ return (
+
+ {
+ const clickedToggleIcon = ['svg', 'path'].includes(
+ (e.target as HTMLElement).tagName.toLowerCase()
+ )
+ if (clickedToggleIcon) {
+ e.preventDefault()
+ }
+ if (isLink) {
+ // If it's focused, we toggle it. Otherwise, always open it.
+ if (active || clickedToggleIcon) {
+ TreeState[item.route] = !open
+ } else {
+ TreeState[item.route] = true
+ setMenu(false)
+ }
+ rerender({})
+ return
+ }
+ if (active) return
+ TreeState[item.route] = !open
+ rerender({})
+ }}
+ >
+ {renderComponent(config.sidebar.titleComponent, {
+ title: item.title,
+ type: item.type,
+ route: item.route
+ })}
+
+
+
+ {Array.isArray(item.children) ? (
+
+ ) : null}
+
+
+ )
+}
+
+function Separator({ title }: { title: string }): ReactElement {
+ const config = useConfig()
+ return (
+
+ {title ? (
+ renderComponent(config.sidebar.titleComponent, {
+ title,
+ type: 'separator',
+ route: ''
+ })
+ ) : (
+
+ )}
+
+ )
+}
+
+function File({
+ item,
+ anchors
+}: {
+ item: PageItem | Item
+ anchors: Heading[]
+}): ReactElement {
+ const route = useFSRoute()
+ const onFocus = useContext(OnFocusItemContext)
+
+ // It is possible that the item doesn't have any route - for example an external link.
+ const active = item.route && [route, route + '/'].includes(item.route + '/')
+ const activeAnchor = useActiveAnchor()
+ const { setMenu } = useMenu()
+ const config = useConfig()
+
+ if (item.type === 'separator') {
+ return
+ }
+
+ return (
+
+ {
+ setMenu(false)
+ }}
+ onFocus={() => {
+ onFocus?.(item.route)
+ }}
+ onBlur={() => {
+ onFocus?.(null)
+ }}
+ >
+ {renderComponent(config.sidebar.titleComponent, {
+ title: item.title,
+ type: item.type,
+ route: item.route
+ })}
+
+ {active && anchors.length > 0 && (
+
+ )}
+
+ )
+}
+
+interface MenuProps {
+ directories: ExtendedPageItem[] | ExtendedItem[]
+ anchors: Heading[]
+ base?: string
+ className?: string
+ onlyCurrentDocs?: boolean
+}
+
+function Menu({
+ directories,
+ anchors,
+ className,
+ onlyCurrentDocs
+}: MenuProps): ReactElement {
+
+ const session = useSession()
+
+ return (
+
+ {directories.map(item => {
+
+ if(!shouldLinkBeRenderedAccordingToUserRole(session, item))
+ return null
+
+ return !onlyCurrentDocs || item.isUnderCurrentDocsTree ? (
+ item.type === 'menu' ||
+ (item.children && (item.children.length || !item.withIndexPage)) ? (
+
+ ) : (
+
+ )
+ ) : null
+ }
+
+ )}
+
+ )
+}
+
+interface SideBarProps {
+ docsDirectories: ExtendedPageItem[] // they have the `private` property
+ flatDirectories: ExtendedItem[] // they DON'T have the `private` property (used for search)
+ fullDirectories: ExtendedItem[] // they have the `private` property
+ asPopover?: boolean
+ headings: Heading[]
+ includePlaceholder: boolean
+}
+
+export function Sidebar({
+ docsDirectories,
+ flatDirectories,
+ fullDirectories,
+ asPopover = false,
+ headings,
+ includePlaceholder
+}: SideBarProps): ReactElement {
+ const config = useConfig()
+ const { menu, setMenu } = useMenu()
+ const router = useRouter()
+ const [focused, setFocused] = useState(null)
+ const [showSidebar, setSidebar] = useState(true)
+ const [showToggleAnimation, setToggleAnimation] = useState(false)
+
+ const anchors = useMemo(() => headings.filter(v => v.depth === 2), [headings])
+ const sidebarRef = useRef(null)
+ const containerRef = useRef(null)
+ const mounted = useMounted()
+ useEffect(() => {
+ if (menu) {
+ document.body.classList.add('nx-overflow-hidden', 'md:nx-overflow-auto')
+ } else {
+ document.body.classList.remove(
+ 'nx-overflow-hidden',
+ 'md:nx-overflow-auto'
+ )
+ }
+ }, [menu])
+
+ useEffect(() => {
+ const activeElement = sidebarRef.current?.querySelector('li.active')
+
+ if (activeElement && (window.innerWidth > 767 || menu)) {
+ const scroll = () => {
+ scrollIntoView(activeElement, {
+ block: 'center',
+ inline: 'center',
+ scrollMode: 'always',
+ boundary: containerRef.current
+ })
+ }
+ if (menu) {
+ // needs for mobile since menu has transition transform
+ setTimeout(scroll, 300)
+ } else {
+ scroll()
+ }
+ }
+ }, [menu])
+
+ // Always close mobile nav when route was changed (e.g. logo click)
+ useEffect(() => {
+ setMenu(false)
+ }, [router.asPath, setMenu])
+
+ const hasI18n = config.i18n.length > 0
+ const hasMenu = config.darkMode || hasI18n || config.sidebar.toggleButton
+
+ return (
+ <>
+ {includePlaceholder && asPopover ? (
+
+ ) : null}
+ setMenu(false)}
+ />
+
+
+ )
+}
diff --git a/theme/src/components/skip-nav.tsx b/theme/src/components/skip-nav.tsx
new file mode 100644
index 0000000..2ede7d8
--- /dev/null
+++ b/theme/src/components/skip-nav.tsx
@@ -0,0 +1,93 @@
+/**
+ * The code included in this file is inspired by https://github.com/reach/reach-ui/blob/43f450db7bcb25a743121fe31355f2294065a049/packages/skip-nav/src/reach-skip-nav.tsx which is part of the @reach/skip-nav library.
+ *
+ * @reach/skip-nav is licensed as follows:
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2018-2023, React Training LLC
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * Source: https://github.com/reach/reach-ui/blob/43f450db7bcb25a743121fe31355f2294065a049/LICENSE
+ */
+import cn from 'clsx'
+import type { ComponentProps, ReactElement } from 'react'
+import { forwardRef } from 'react'
+
+// TODO: Change the DEFAULT_ID for `nextra-skip-nav` or something else on the next major version (v3.x). The DEFAULT_ID must be 'reach-skip-nav' because changing this value is a breaking change for users that use v2.0.1 and earlier
+const DEFAULT_ID = 'reach-skip-nav'
+const DEFAULT_LABEL = 'Skip to content'
+
+type SkipNavLinkProps = Omit<
+ ComponentProps<'a'>,
+ 'ref' | 'href' | 'children'
+> & {
+ label?: string
+ styled?: boolean
+}
+
+export const SkipNavLink = forwardRef
(
+ function (
+ {
+ className: providedClassName,
+ id,
+ label = DEFAULT_LABEL,
+ styled,
+ ...props
+ },
+ forwardedRef
+ ): ReactElement {
+ const className =
+ providedClassName === undefined // Give the option to the user to pass a falsy other than undefined to remove the default styles
+ ? styled // Give the user a way to opt-in the default style provided with the theme. Probably remove this option in the next major version (v3.x) and just do a check to use the providedClassName or the default
+ ? cn(
+ 'nx-sr-only',
+ 'focus:nx-not-sr-only focus:nx-fixed focus:nx-z-50 focus:nx-m-3 focus:nx-ml-4 focus:nx-h-[calc(var(--nextra-navbar-height)-1.5rem)] focus:nx-rounded-lg focus:nx-border focus:nx-px-3 focus:nx-py-2 focus:nx-align-middle focus:nx-text-sm focus:nx-font-bold',
+ 'focus:nx-text-gray-900 focus:dark:nx-text-gray-100',
+ 'focus:nx-bg-white focus:dark:nx-bg-neutral-900',
+ 'focus:nx-border-neutral-400 focus:dark:nx-border-neutral-800'
+ )
+ : ''
+ : providedClassName
+
+ return (
+
+ {label}
+
+ )
+ }
+)
+
+SkipNavLink.displayName = 'SkipNavLink'
+
+type SkipNavContentProps = Omit, 'ref' | 'children'>
+
+export const SkipNavContent = forwardRef(
+ function ({ id, ...props }, forwardedRef): ReactElement {
+ return
+ }
+)
+
+SkipNavContent.displayName = 'SkipNavContent'
diff --git a/theme/src/components/theme-switch.tsx b/theme/src/components/theme-switch.tsx
new file mode 100644
index 0000000..8c0a27d
--- /dev/null
+++ b/theme/src/components/theme-switch.tsx
@@ -0,0 +1,61 @@
+import { useTheme } from 'next-themes'
+import { useMounted } from 'nextra/hooks'
+import { MoonIcon, SunIcon } from 'nextra/icons'
+import type { ReactElement } from 'react'
+import { z } from 'zod'
+import { useConfig } from '../contexts'
+import { Select } from './select'
+
+type ThemeSwitchProps = {
+ lite?: boolean
+ className?: string
+}
+
+export const themeOptionsSchema = z.strictObject({
+ light: z.string(),
+ dark: z.string(),
+ system: z.string()
+})
+
+type ThemeOptions = z.infer
+
+export function ThemeSwitch({
+ lite,
+ className
+}: ThemeSwitchProps): ReactElement {
+ const { setTheme, resolvedTheme, theme = '' } = useTheme()
+ const mounted = useMounted()
+ const config = useConfig().themeSwitch
+
+ const IconToUse = mounted && resolvedTheme === 'dark' ? MoonIcon : SunIcon
+ const options: ThemeOptions =
+ typeof config.useOptions === 'function'
+ ? config.useOptions()
+ : config.useOptions
+
+ return (
+
+ {summary}
+ {restChildren}
+
+ )
+}
+
+const Summary = (props: ComponentProps<'summary'>): ReactElement => {
+ const setOpen = useDetails()
+ return (
+ &]:before:nx-rotate-90'
+ )}
+ {...props}
+ onClick={e => {
+ e.preventDefault()
+ setOpen(v => !v)
+ }}
+ />
+ )
+}
+
+const EXTERNAL_HREF_REGEX = /https?:\/\//
+
+export const Link = ({ href = '', className, ...props }: AnchorProps) => (
+
+)
+
+const A = ({ href = '', ...props }) => (
+
+)
+
+export const getComponents = ({
+ isRawLayout,
+ components
+}: {
+ isRawLayout?: boolean
+ components?: DocsThemeConfig['components']
+}): Components => {
+ if (isRawLayout) {
+ return { a: A }
+ }
+
+ const context = { index: 0 }
+ return {
+ h1: props => (
+
+ ),
+ h2: props => ,
+ h3: props => ,
+ h4: props => ,
+ h5: props => ,
+ h6: props => ,
+ ul: props => (
+
+ ),
+ ol: props => (
+
+ ),
+ li: props => ,
+ blockquote: props => (
+
+ ),
+ hr: props => (
+
+ ),
+ a: Link,
+ table: props => (
+
+ ),
+ p: props => ,
+ tr: Tr,
+ th: Th,
+ td: Td,
+ details: Details,
+ summary: Summary,
+ pre: Pre,
+ code: Code,
+ ...components
+ }
+}
diff --git a/theme/src/nextra_components/button.tsx b/theme/src/nextra_components/button.tsx
new file mode 100644
index 0000000..58288b3
--- /dev/null
+++ b/theme/src/nextra_components/button.tsx
@@ -0,0 +1,22 @@
+import cn from 'clsx'
+import type { ComponentProps, ReactElement } from 'react'
+
+export const Button = ({
+ children,
+ className,
+ ...props
+}: ComponentProps<'button'>): ReactElement => {
+ return (
+
+ )
+}
diff --git a/theme/src/nextra_components/callout.tsx b/theme/src/nextra_components/callout.tsx
new file mode 100644
index 0000000..2c168a0
--- /dev/null
+++ b/theme/src/nextra_components/callout.tsx
@@ -0,0 +1,59 @@
+import cn from 'clsx'
+import type { ReactElement, ReactNode } from 'react'
+import { InformationCircleIcon } from '../nextra_icons'
+
+const TypeToEmoji = {
+ default: '๐ก',
+ error: '๐ซ',
+ info: ,
+ warning: 'โ ๏ธ'
+}
+
+type CalloutType = keyof typeof TypeToEmoji
+
+const classes: Record = {
+ default: cn(
+ 'nx-border-orange-100 nx-bg-orange-50 nx-text-orange-800 dark:nx-border-orange-400/30 dark:nx-bg-orange-400/20 dark:nx-text-orange-300'
+ ),
+ error: cn(
+ 'nx-border-red-200 nx-bg-red-100 nx-text-red-900 dark:nx-border-red-200/30 dark:nx-bg-red-900/30 dark:nx-text-red-200'
+ ),
+ info: cn(
+ 'nx-border-blue-200 nx-bg-blue-100 nx-text-blue-900 dark:nx-border-blue-200/30 dark:nx-bg-blue-900/30 dark:nx-text-blue-200'
+ ),
+ warning: cn(
+ 'nx-border-yellow-100 nx-bg-yellow-50 nx-text-yellow-900 dark:nx-border-yellow-200/30 dark:nx-bg-yellow-700/30 dark:nx-text-yellow-200'
+ )
+}
+
+type CalloutProps = {
+ type?: CalloutType
+ emoji?: string | ReactNode
+ children: ReactNode
+}
+
+export function Callout({
+ children,
+ type = 'default',
+ emoji = TypeToEmoji[type]
+}: CalloutProps): ReactElement {
+ return (
+
+
+ {emoji}
+
+
{children}
+
+ {children}
+
+ )
+}
+
+export const Cards = Object.assign(_Cards, { displayName: 'Cards', Card })
diff --git a/theme/src/nextra_components/code.tsx b/theme/src/nextra_components/code.tsx
new file mode 100644
index 0000000..3559a0b
--- /dev/null
+++ b/theme/src/nextra_components/code.tsx
@@ -0,0 +1,25 @@
+import cn from 'clsx'
+import type { ComponentProps, ReactElement } from 'react'
+
+export const Code = ({
+ children,
+ className,
+ ...props
+}: ComponentProps<'code'>): ReactElement => {
+ const hasLineNumbers = 'data-line-numbers' in props
+ return (
+
+ {children}
+
+ )
+}
diff --git a/theme/src/nextra_components/copy-to-clipboard.tsx b/theme/src/nextra_components/copy-to-clipboard.tsx
new file mode 100644
index 0000000..1e9c8d7
--- /dev/null
+++ b/theme/src/nextra_components/copy-to-clipboard.tsx
@@ -0,0 +1,46 @@
+import type { ComponentProps, ReactElement } from 'react'
+import { useCallback, useEffect, useState } from 'react'
+import { CheckIcon, CopyIcon } from '../nextra_icons'
+import { Button } from './button'
+
+export const CopyToClipboard = ({
+ getValue,
+ ...props
+}: {
+ getValue: () => string
+} & ComponentProps<'button'>): ReactElement => {
+ const [isCopied, setCopied] = useState(false)
+
+ useEffect(() => {
+ if (!isCopied) return
+ const timerId = setTimeout(() => {
+ setCopied(false)
+ }, 2000)
+
+ return () => {
+ clearTimeout(timerId)
+ }
+ }, [isCopied])
+
+ const handleClick = useCallback<
+ NonNullable['onClick']>
+ >(async () => {
+ setCopied(true)
+ if (!navigator?.clipboard) {
+ console.error('Access to clipboard rejected!')
+ }
+ try {
+ await navigator.clipboard.writeText(getValue())
+ } catch {
+ console.error('Failed to copy!')
+ }
+ }, [getValue])
+
+ const IconToUse = isCopied ? CheckIcon : CopyIcon
+
+ return (
+
+ )
+}
diff --git a/theme/src/nextra_components/file-tree.tsx b/theme/src/nextra_components/file-tree.tsx
new file mode 100644
index 0000000..1372bd7
--- /dev/null
+++ b/theme/src/nextra_components/file-tree.tsx
@@ -0,0 +1,124 @@
+import cn from 'clsx'
+import { createContext, memo, useCallback, useContext, useState } from 'react'
+import type { ReactElement, ReactNode } from 'react'
+
+const ctx = createContext(0)
+
+function useIndent() {
+ return useContext(ctx)
+}
+
+interface FolderProps {
+ name: string
+ label?: ReactElement
+ open?: boolean
+ defaultOpen?: boolean
+ onToggle?: (open: boolean) => void
+ children: ReactNode
+}
+
+interface FileProps {
+ name: string
+ label?: ReactElement
+ active?: boolean
+}
+
+function Tree({ children }: { children: ReactNode }): ReactElement {
+ return (
+
+ )
+}
+
+function Ident(): ReactElement {
+ const length = useIndent()
+ return (
+ <>
+ {Array.from({ length }, (_, i) => (
+
+ ))}
+
+ )
+}
+
+const Folder = memo(
+ ({ label, name, open, children, defaultOpen = false, onToggle }) => {
+ const indent = useIndent()
+ const [isOpen, setIsOpen] = useState(defaultOpen)
+
+ const toggle = useCallback(() => {
+ onToggle?.(!isOpen)
+ setIsOpen(!isOpen)
+ }, [isOpen, onToggle])
+
+ const isFolderOpen = open === undefined ? isOpen : open
+
+ return (
+
+
+ {isFolderOpen && (
+
+ )}
+
+ )
+ }
+)
+Folder.displayName = 'Folder'
+
+const File = memo(({ label, name, active }) => (
+
+
+
+
+ {label ?? name}
+
+
+))
+File.displayName = 'File'
+
+export const FileTree = Object.assign(Tree, { Folder, File })
diff --git a/theme/src/nextra_components/index.ts b/theme/src/nextra_components/index.ts
new file mode 100644
index 0000000..7342a10
--- /dev/null
+++ b/theme/src/nextra_components/index.ts
@@ -0,0 +1,17 @@
+export { Button } from './button'
+export { Callout } from './callout'
+export { CopyToClipboard } from './copy-to-clipboard'
+export { Code } from './code'
+export { Pre } from './pre'
+export { Steps } from './steps'
+export { Tabs, Tab } from './tabs'
+export { Td } from './td'
+export { Table } from './table'
+export { Th } from './th'
+export { Tr } from './tr'
+export { Cards, Card } from './cards'
+export { FileTree } from './file-tree'
+// This should throw an error because it's from `nextra`, which is not directly accessible.
+// But it will still work, we don't need the types, since this package just replaces ```mermaid``` code blocks into ` React components
+// @ts-expect-error
+export { Mermaid } from '@theguild/remark-mermaid/mermaid'
diff --git a/theme/src/nextra_components/pre.tsx b/theme/src/nextra_components/pre.tsx
new file mode 100644
index 0000000..473504b
--- /dev/null
+++ b/theme/src/nextra_components/pre.tsx
@@ -0,0 +1,73 @@
+import cn from 'clsx'
+import type { ComponentProps, ReactElement } from 'react'
+import { useCallback, useRef } from 'react'
+import { WordWrapIcon } from '../nextra_icons'
+import { Button } from './button'
+import { CopyToClipboard } from './copy-to-clipboard'
+
+export const Pre = ({
+ children,
+ className,
+ hasCopyCode,
+ filename,
+ ...props
+}: ComponentProps<'pre'> & {
+ filename?: string
+ hasCopyCode?: boolean
+}): ReactElement => {
+ const preRef = useRef(null)
+
+ const toggleWordWrap = useCallback(() => {
+ const htmlDataset = document.documentElement.dataset
+ const hasWordWrap = 'nextraWordWrap' in htmlDataset
+ if (hasWordWrap) {
+ delete htmlDataset.nextraWordWrap
+ } else {
+ htmlDataset.nextraWordWrap = ''
+ }
+ }, [])
+
+ return (
+
+ {filename && (
+
+ {filename}
+
+ )}
+
+ {children}
+
+
&]:nx-opacity-100 focus-within:nx-opacity-100',
+ 'nx-flex nx-gap-1 nx-absolute nx-m-[11px] nx-right-0',
+ filename ? 'nx-top-8' : 'nx-top-0'
+ )}
+ >
+
+ {hasCopyCode && (
+
+ preRef.current?.querySelector('code')?.textContent || ''
+ }
+ />
+ )}
+
+
+ {children}
+
+ )
+}
diff --git a/theme/src/nextra_components/table.tsx b/theme/src/nextra_components/table.tsx
new file mode 100644
index 0000000..d8542a6
--- /dev/null
+++ b/theme/src/nextra_components/table.tsx
@@ -0,0 +1,12 @@
+import cn from 'clsx'
+import type { ComponentProps } from 'react'
+
+export const Table = ({
+ className = '',
+ ...props
+}: ComponentProps<'table'>) => (
+
+)
diff --git a/theme/src/nextra_components/tabs.tsx b/theme/src/nextra_components/tabs.tsx
new file mode 100644
index 0000000..41fe429
--- /dev/null
+++ b/theme/src/nextra_components/tabs.tsx
@@ -0,0 +1,125 @@
+import { Tab as HeadlessTab } from '@headlessui/react'
+import cn from 'clsx'
+import type { ComponentProps, ReactElement, ReactNode } from 'react'
+import { useCallback, useEffect, useState } from 'react'
+
+type TabItem = string | ReactNode
+
+type TabObjectItem = {
+ label: TabItem
+ disabled: boolean
+}
+
+function isTabObjectItem(item: unknown): item is TabObjectItem {
+ return !!item && typeof item === 'object' && 'label' in item
+}
+
+function _Tabs({
+ items,
+ selectedIndex: _selectedIndex,
+ defaultIndex = 0,
+ onChange,
+ children,
+ storageKey
+}: {
+ items: (TabItem | TabObjectItem)[]
+ selectedIndex?: number
+ defaultIndex?: number
+ onChange?: (index: number) => void
+ children: ReactNode
+ storageKey?: string
+}): ReactElement {
+ const [selectedIndex, setSelectedIndex] = useState(defaultIndex)
+
+ useEffect(() => {
+ if (_selectedIndex !== undefined) {
+ setSelectedIndex(_selectedIndex)
+ }
+ }, [_selectedIndex])
+
+ useEffect(() => {
+ if (!storageKey) {
+ // Do not listen storage events if there is no storage key
+ return
+ }
+
+ function fn(event: StorageEvent) {
+ if (event.key === storageKey) {
+ setSelectedIndex(Number(event.newValue))
+ }
+ }
+
+ const index = Number(localStorage.getItem(storageKey))
+ setSelectedIndex(Number.isNaN(index) ? 0 : index)
+
+ window.addEventListener('storage', fn)
+ return () => {
+ window.removeEventListener('storage', fn)
+ }
+ }, []) // eslint-disable-line react-hooks/exhaustive-deps -- only on mount
+
+ const handleChange = useCallback((index: number) => {
+ if (storageKey) {
+ const newValue = String(index)
+ localStorage.setItem(storageKey, newValue)
+
+ // the storage event only get picked up (by the listener) if the localStorage was changed in
+ // another browser's tab/window (of the same app), but not within the context of the current tab.
+ window.dispatchEvent(
+ new StorageEvent('storage', { key: storageKey, newValue })
+ )
+ return
+ }
+ setSelectedIndex(index)
+ onChange?.(index)
+ }, []) // eslint-disable-line react-hooks/exhaustive-deps -- only on mount
+
+ return (
+
+
+
+ {items.map((item, index) => {
+ const disabled = isTabObjectItem(item) && item.disabled
+ return (
+
+ cn(
+ 'nx-mr-2 nx-rounded-t nx-p-2 nx-font-medium nx-leading-5 nx-transition-colors',
+ '-nx-mb-0.5 nx-select-none nx-border-b-2',
+ selected
+ ? 'nx-border-primary-500 nx-text-primary-600'
+ : 'nx-border-transparent nx-text-gray-600 hover:nx-border-gray-200 hover:nx-text-black dark:nx-text-gray-200 dark:hover:nx-border-neutral-800 dark:hover:nx-text-white',
+ disabled &&
+ 'nx-pointer-events-none nx-text-gray-400 dark:nx-text-neutral-600'
+ )
+ }
+ >
+ {isTabObjectItem(item) ? item.label : item}
+
+ )
+ })}
+
+
+ {children}
+
+ )
+}
+
+export function Tab({
+ children,
+ ...props
+}: ComponentProps): ReactElement {
+ return (
+
+ {children}
+
+ )
+}
+
+export const Tabs = Object.assign(_Tabs, { displayName: 'Tabs', Tab })
diff --git a/theme/src/nextra_components/td.tsx b/theme/src/nextra_components/td.tsx
new file mode 100644
index 0000000..a0379cf
--- /dev/null
+++ b/theme/src/nextra_components/td.tsx
@@ -0,0 +1,12 @@
+import cn from 'clsx'
+import type { ComponentProps } from 'react'
+
+export const Td = ({ className = '', ...props }: ComponentProps<'td'>) => (
+ |
+)
diff --git a/theme/src/nextra_components/th.tsx b/theme/src/nextra_components/th.tsx
new file mode 100644
index 0000000..f7cc09f
--- /dev/null
+++ b/theme/src/nextra_components/th.tsx
@@ -0,0 +1,12 @@
+import cn from 'clsx'
+import type { ComponentProps } from 'react'
+
+export const Th = ({ className = '', ...props }: ComponentProps<'th'>) => (
+ |
+)
diff --git a/theme/src/nextra_components/tr.tsx b/theme/src/nextra_components/tr.tsx
new file mode 100644
index 0000000..e39366f
--- /dev/null
+++ b/theme/src/nextra_components/tr.tsx
@@ -0,0 +1,13 @@
+import cn from 'clsx'
+import type { ComponentProps } from 'react'
+
+export const Tr = ({ className = '', ...props }: ComponentProps<'tr'>) => (
+ |
+)
diff --git a/theme/src/nextra_icons/arrow-right.tsx b/theme/src/nextra_icons/arrow-right.tsx
new file mode 100644
index 0000000..663a46b
--- /dev/null
+++ b/theme/src/nextra_icons/arrow-right.tsx
@@ -0,0 +1,18 @@
+import type { ComponentProps, ReactElement } from 'react'
+
+export function ArrowRightIcon({
+ pathClassName,
+ ...props
+}: ComponentProps<'svg'> & { pathClassName?: string }): ReactElement {
+ return (
+
+ )
+}
diff --git a/theme/src/nextra_icons/check.tsx b/theme/src/nextra_icons/check.tsx
new file mode 100644
index 0000000..47c8739
--- /dev/null
+++ b/theme/src/nextra_icons/check.tsx
@@ -0,0 +1,19 @@
+import type { ComponentProps, ReactElement } from 'react'
+
+export function CheckIcon(props: ComponentProps<'svg'>): ReactElement {
+ return (
+
+ )
+}
diff --git a/theme/src/nextra_icons/copy.tsx b/theme/src/nextra_icons/copy.tsx
new file mode 100644
index 0000000..a0198e0
--- /dev/null
+++ b/theme/src/nextra_icons/copy.tsx
@@ -0,0 +1,32 @@
+import type { ComponentProps, ReactElement } from 'react'
+
+export function CopyIcon(props: ComponentProps<'svg'>): ReactElement {
+ return (
+
+ )
+}
diff --git a/theme/src/nextra_icons/discord.tsx b/theme/src/nextra_icons/discord.tsx
new file mode 100644
index 0000000..65a8aed
--- /dev/null
+++ b/theme/src/nextra_icons/discord.tsx
@@ -0,0 +1,17 @@
+import type { ComponentProps, ReactElement } from 'react'
+
+export function DiscordIcon(props: ComponentProps<'svg'>): ReactElement {
+ return (
+
+ )
+}
diff --git a/theme/src/nextra_icons/expand.tsx b/theme/src/nextra_icons/expand.tsx
new file mode 100644
index 0000000..dbf06de
--- /dev/null
+++ b/theme/src/nextra_icons/expand.tsx
@@ -0,0 +1,26 @@
+import type { ComponentProps, ReactElement } from 'react'
+
+export function ExpandIcon({
+ isOpen,
+ ...props
+}: { isOpen?: boolean } & ComponentProps<'svg'>): ReactElement {
+ return (
+
+ )
+}
diff --git a/theme/src/nextra_icons/github.tsx b/theme/src/nextra_icons/github.tsx
new file mode 100644
index 0000000..da2a204
--- /dev/null
+++ b/theme/src/nextra_icons/github.tsx
@@ -0,0 +1,16 @@
+import type { ComponentProps, ReactElement } from 'react'
+
+export function GitHubIcon(props: ComponentProps<'svg'>): ReactElement {
+ return (
+
+ )
+}
diff --git a/theme/src/nextra_icons/globe.tsx b/theme/src/nextra_icons/globe.tsx
new file mode 100644
index 0000000..4e1afd9
--- /dev/null
+++ b/theme/src/nextra_icons/globe.tsx
@@ -0,0 +1,19 @@
+import type { ComponentProps, ReactElement } from 'react'
+
+export function GlobeIcon(props: ComponentProps<'svg'>): ReactElement {
+ return (
+
+ )
+}
diff --git a/theme/src/nextra_icons/index.ts b/theme/src/nextra_icons/index.ts
new file mode 100644
index 0000000..5073f8c
--- /dev/null
+++ b/theme/src/nextra_icons/index.ts
@@ -0,0 +1,14 @@
+export * from './arrow-right'
+export * from './check'
+export * from './copy'
+export * from './discord'
+export * from './expand'
+export * from './github'
+export * from './globe'
+export * from './information-circle'
+export * from './menu'
+export * from './moon'
+export * from './spinner'
+export * from './sun'
+export * from './word-wrap'
+export * from './x'
diff --git a/theme/src/nextra_icons/information-circle.tsx b/theme/src/nextra_icons/information-circle.tsx
new file mode 100644
index 0000000..13ff76b
--- /dev/null
+++ b/theme/src/nextra_icons/information-circle.tsx
@@ -0,0 +1,22 @@
+import type { ComponentProps, ReactElement } from 'react'
+
+export function InformationCircleIcon(
+ props: ComponentProps<'svg'>
+): ReactElement {
+ return (
+
+ )
+}
diff --git a/theme/src/nextra_icons/menu.tsx b/theme/src/nextra_icons/menu.tsx
new file mode 100644
index 0000000..b6432a1
--- /dev/null
+++ b/theme/src/nextra_icons/menu.tsx
@@ -0,0 +1,37 @@
+import type { ComponentProps, ReactElement } from 'react'
+
+export function MenuIcon(props: ComponentProps<'svg'>): ReactElement {
+ return (
+
+ )
+}
diff --git a/theme/src/nextra_icons/moon.tsx b/theme/src/nextra_icons/moon.tsx
new file mode 100644
index 0000000..2695524
--- /dev/null
+++ b/theme/src/nextra_icons/moon.tsx
@@ -0,0 +1,22 @@
+import type { ComponentProps, ReactElement } from 'react'
+
+export function MoonIcon(props: ComponentProps<'svg'>): ReactElement {
+ return (
+
+ )
+}
diff --git a/theme/src/nextra_icons/spinner.tsx b/theme/src/nextra_icons/spinner.tsx
new file mode 100644
index 0000000..738d84d
--- /dev/null
+++ b/theme/src/nextra_icons/spinner.tsx
@@ -0,0 +1,28 @@
+import type { ComponentProps, ReactElement } from 'react'
+
+export function SpinnerIcon(props: ComponentProps<'svg'>): ReactElement {
+ return (
+
+ )
+}
diff --git a/theme/src/nextra_icons/sun.tsx b/theme/src/nextra_icons/sun.tsx
new file mode 100644
index 0000000..9cfee6d
--- /dev/null
+++ b/theme/src/nextra_icons/sun.tsx
@@ -0,0 +1,22 @@
+import type { ComponentProps, ReactElement } from 'react'
+
+export function SunIcon(props: ComponentProps<'svg'>): ReactElement {
+ return (
+
+ )
+}
diff --git a/theme/src/nextra_icons/word-wrap.tsx b/theme/src/nextra_icons/word-wrap.tsx
new file mode 100644
index 0000000..41a512e
--- /dev/null
+++ b/theme/src/nextra_icons/word-wrap.tsx
@@ -0,0 +1,12 @@
+import type { ComponentProps, ReactElement } from 'react'
+
+export function WordWrapIcon(props: ComponentProps<'svg'>): ReactElement {
+ return (
+
+ )
+}
diff --git a/theme/src/nextra_icons/x.tsx b/theme/src/nextra_icons/x.tsx
new file mode 100644
index 0000000..2eb8e3e
--- /dev/null
+++ b/theme/src/nextra_icons/x.tsx
@@ -0,0 +1,20 @@
+import type { ComponentProps, ReactElement } from 'react'
+
+export function XIcon(props: ComponentProps<'svg'>): ReactElement {
+ return (
+
+ )
+}
diff --git a/theme/src/polyfill.ts b/theme/src/polyfill.ts
new file mode 100644
index 0000000..1cba2af
--- /dev/null
+++ b/theme/src/polyfill.ts
@@ -0,0 +1,15 @@
+import { IS_BROWSER } from './contexts/config'
+
+if (IS_BROWSER) {
+ let resizeTimer: any
+
+ const addResizingClass = () => {
+ document.body.classList.add('resizing')
+ clearTimeout(resizeTimer)
+ resizeTimer = setTimeout(() => {
+ document.body.classList.remove('resizing')
+ }, 200)
+ }
+
+ window.addEventListener('resize', addResizingClass)
+}
diff --git a/theme/src/types.ts b/theme/src/types.ts
new file mode 100644
index 0000000..5534871
--- /dev/null
+++ b/theme/src/types.ts
@@ -0,0 +1,23 @@
+/* eslint typescript-sort-keys/interface: error */
+import type { PageOpts } from 'nextra'
+import type { ReactNode } from 'react'
+import type { DocsThemeConfig } from './contexts/config'
+import type { Item, MenuItem, PageItem } from 'nextra/normalize-pages'
+import { PrivateInfo } from '../../src/types';
+
+export type Context = {
+ pageOpts: PageOpts
+ themeConfig: DocsThemeConfig
+}
+
+export type SearchResult = {
+ children: ReactNode
+ id: string
+ prefix?: ReactNode
+ route: string
+}
+
+// Extends the PageItem and MenuItem with the `private` property
+export type ExtendedPageItem = { private?: PrivateInfo } & PageItem;
+export type ExtendedMenuItem = { private?: PrivateInfo } & MenuItem;
+export type ExtendedItem = { private?: PrivateInfo } & Item;
diff --git a/theme/src/utils/get-git-issue-url.ts b/theme/src/utils/get-git-issue-url.ts
new file mode 100644
index 0000000..4898765
--- /dev/null
+++ b/theme/src/utils/get-git-issue-url.ts
@@ -0,0 +1,30 @@
+import gitUrlParse from 'git-url-parse'
+
+export const getGitIssueUrl = ({
+ repository = '',
+ title,
+ labels
+}: {
+ repository?: string
+ title: string
+ labels?: string
+}): string => {
+ const repo = gitUrlParse(repository)
+ if (!repo) throw new Error('Invalid `docsRepositoryBase` URL!')
+
+ if (repo.resource.includes('gitlab')) {
+ return `${repo.protocol}://${repo.resource}/${repo.owner}/${
+ repo.name
+ }/-/issues/new?issue[title]=${encodeURIComponent(title)}${
+ labels
+ ? `&issue[description]=/label${encodeURIComponent(` ~${labels}\n`)}`
+ : ''
+ }`
+ }
+ if (repo.resource.includes('github')) {
+ return `${repo.protocol}://${repo.resource}/${repo.owner}/${
+ repo.name
+ }/issues/new?title=${encodeURIComponent(title)}&labels=${labels || ''}`
+ }
+ return '#'
+}
diff --git a/theme/src/utils/index.ts b/theme/src/utils/index.ts
new file mode 100644
index 0000000..4b3cefd
--- /dev/null
+++ b/theme/src/utils/index.ts
@@ -0,0 +1,4 @@
+export { getGitIssueUrl } from './get-git-issue-url'
+export { renderComponent, renderString } from './render'
+export { usePopper } from './use-popper'
+export { useGitEditUrl } from './use-git-edit-url'
diff --git a/theme/src/utils/render.tsx b/theme/src/utils/render.tsx
new file mode 100644
index 0000000..29eeda4
--- /dev/null
+++ b/theme/src/utils/render.tsx
@@ -0,0 +1,57 @@
+import { SessionContextValue } from "next-auth/react";
+import type { FC, ReactNode } from "react";
+import { ExtendedUser } from "../../../src/types";
+import { ExtendedItem, ExtendedPageItem, ExtendedMenuItem } from "../types";
+
+export function renderComponent(ComponentOrNode: FC | ReactNode, props?: T) {
+ if (!ComponentOrNode) return null;
+ if (typeof ComponentOrNode !== "function") return ComponentOrNode;
+ // @ts-expect-error TS2322: Type '{}' is not assignable to type 'T'
+ return ;
+}
+
+export function renderString(
+ stringOrFunction?: string | ((props: T) => string),
+ // @ts-expect-error TS2322: Type '{}' is not assignable to type 'T'.
+ props: T = {}
+): string {
+ const result = typeof stringOrFunction === "function" ? stringOrFunction(props) : stringOrFunction;
+ return result || "";
+}
+
+/**
+ * This functions tells if the user can see a given `navbar` or `sidebar` link item
+ * according to its role.
+ * @param session session from the user.
+ * @param item item (can either be a page item, menu item or normal item)
+ * @returns true if the link can be shown to the user. False if the user doesn't have authorization to see the link.
+ */
+export function shouldLinkBeRenderedAccordingToUserRole(
+ session: SessionContextValue,
+ item: ExtendedItem | ExtendedPageItem | ExtendedMenuItem
+) {
+ const { data, status: session_status } = session;
+ const user = data?.user as ExtendedUser;
+
+ // Wait until the session is fetched (be it empty or authenticated)
+ if (session_status === "loading") return false;
+
+ // If it's a public user but the link is marked as private, hide it
+ if (session_status === "unauthenticated") {
+ if (item.private) return false;
+ }
+
+ // If the user is authenticated
+ // and the page menu is protected or the role of the user is not present in the array, we block it
+ if (session_status === "authenticated" && user) {
+ if (item.private?.private) {
+ const neededRoles = item.private.roles || [];
+ const userRole = user.role;
+ if (!userRole || !neededRoles.includes(userRole)) {
+ return false;
+ }
+ }
+ }
+
+ return true;
+}
diff --git a/theme/src/utils/use-git-edit-url.ts b/theme/src/utils/use-git-edit-url.ts
new file mode 100644
index 0000000..e7b5661
--- /dev/null
+++ b/theme/src/utils/use-git-edit-url.ts
@@ -0,0 +1,11 @@
+import gitUrlParse from 'git-url-parse'
+import { useConfig } from '../contexts'
+
+export function useGitEditUrl(filePath = ''): string {
+ const config = useConfig()
+ const repo = gitUrlParse(config.docsRepositoryBase || '')
+
+ if (!repo) throw new Error('Invalid `docsRepositoryBase` URL!')
+
+ return `${repo.href}/${filePath}`
+}
diff --git a/theme/src/utils/use-popper.ts b/theme/src/utils/use-popper.ts
new file mode 100644
index 0000000..192535b
--- /dev/null
+++ b/theme/src/utils/use-popper.ts
@@ -0,0 +1,42 @@
+import type { Options } from '@popperjs/core'
+import { createPopper } from '@popperjs/core'
+import type { RefCallback } from 'react'
+import { useCallback, useMemo, useRef } from 'react'
+
+/**
+ * https://github.com/tailwindlabs/headlessui/issues/59
+ * Example implementation to use Popper: https://popper.js.org
+ */
+export function usePopper(
+ options?: Partial
+): [RefCallback, RefCallback] {
+ const reference = useRef(null)
+ const popper = useRef(null)
+
+ const cleanupCallback = useRef<() => void>()
+
+ const instantiatePopper = useCallback(() => {
+ if (!reference.current || !popper.current) return
+
+ cleanupCallback.current?.()
+ cleanupCallback.current = createPopper(
+ reference.current,
+ popper.current,
+ options
+ ).destroy
+ }, [reference, popper, cleanupCallback, options])
+
+ return useMemo(
+ () => [
+ referenceDomNode => {
+ reference.current = referenceDomNode
+ instantiatePopper()
+ },
+ popperDomNode => {
+ popper.current = popperDomNode
+ instantiatePopper()
+ }
+ ],
+ [reference, popper, instantiatePopper]
+ )
+}
diff --git a/theme/tsconfig.json b/theme/tsconfig.json
new file mode 100644
index 0000000..006f76e
--- /dev/null
+++ b/theme/tsconfig.json
@@ -0,0 +1,21 @@
+{
+ "compilerOptions": {
+ "target": "es2016",
+ "module": "ESNext",
+ "declaration": false,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "strict": true,
+ "skipLibCheck": true,
+ "allowJs": true,
+ "jsx": "react-jsx",
+ "moduleResolution": "node",
+ "lib": ["ESNext", "DOM", "DOM.Iterable"],
+ "types": ["vitest/globals"],
+ "resolveJsonModule": true,
+ "paths": {
+ // fixes incorrect types for flexsearch https://github.com/nextapps-de/flexsearch/issues/392#issuecomment-1552286514
+ "flexsearch": ["./node_modules/@types/flexsearch"]
+ }
+ }
+}
diff --git a/theme/tsup.config.ts b/theme/tsup.config.ts
new file mode 100644
index 0000000..3f4b5b5
--- /dev/null
+++ b/theme/tsup.config.ts
@@ -0,0 +1,12 @@
+// Can't find 'tsup' but it runs correctly (for some reason). This may be an issue with how the workspace is define.
+// @ts-ignore
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+ name: 'nextra-theme-docs',
+ entry: ['src/index.tsx'],
+ format: 'esm',
+ dts: true,
+ external: ['nextra'],
+ outExtension: () => ({ js: '.js' })
+})
diff --git a/theme/vite.config.ts b/theme/vite.config.ts
new file mode 100644
index 0000000..c2e7b68
--- /dev/null
+++ b/theme/vite.config.ts
@@ -0,0 +1,9 @@
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+ plugins: [react()],
+ test: {
+ environment: 'jsdom'
+ }
+})
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 0000000..f3d3061
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,43 @@
+{
+ "compilerOptions": {
+ "target": "es5",
+ "lib": ["dom", "dom.iterable", "esnext"],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "preserve",
+ "incremental": true,
+ "plugins": [
+ {
+ "name": "next"
+ }
+ ],
+ "paths": {
+ "@/*": ["./*"]
+ }
+ },
+ "include": [
+ "next-env.d.ts",
+ "*/**/*.ts",
+ "**/*.ts",
+ "**/*.tsx",
+ ".next/types/**/*.ts",
+ "src/app/lib/placeholder-data.js",
+ "scripts/seed.js"
+ ],
+ "exclude": ["node_modules"],
+
+ // These are only used by `ts-node` to run the script that generates the private routes.
+ // These options are overrides used only by ts-node, same as the --compilerOptions flag and the TS_NODE_COMPILER_OPTIONS environment variable
+ "ts-node": {
+ "compilerOptions": {
+ "module": "commonjs"
+ }
+ },
+}
\ No newline at end of file
diff --git a/tutorial.md b/tutorial.md
new file mode 100644
index 0000000..eb5376b
--- /dev/null
+++ b/tutorial.md
@@ -0,0 +1,2411 @@
+
+
+# `Nextra` _Tutorial_
+
+
+
+- [`Nextra` _Tutorial_](#nextra-tutorial)
+ - [0. Start a new project ๐](#0-start-a-new-project-)
+ - [1. Organize Your Content ๐](#1-organize-your-content-)
+ - [1.1 External Links and Hidden Routes ๐](#11-external-links-and-hidden-routes-)
+ - [1.2 Adding items to the navbar](#12-adding-items-to-the-navbar)
+ - [2. Add Authentication ๐](#2-add-authentication-)
+ - [2.1 Adding Github provider](#21-adding-github-provider)
+ - [2.2 Letting people `Sign In` and `Sign Out`](#22-letting-people-sign-in-and-sign-out)
+ - [3. Protecting routes](#3-protecting-routes)
+ - [3.1 A word about `middleware.ts`](#31-a-word-about-middlewarets)
+ - [3.2 Adding `middleware.ts` logic](#32-adding-middlewarets-logic)
+ - [3.3 Configuring `auth.ts`](#33-configuring-authts)
+ - [4. Generating private routes](#4-generating-private-routes)
+ - [4.1 Installing `ts-morph` and setup](#41-installing-ts-morph-and-setup)
+ - [4.2 Creating `generatePrivateRoutes.ts`](#42-creating-generateprivateroutests)
+ - [4.3 Implementing private route retrieval function](#43-implementing-private-route-retrieval-function)
+ - [4.3.1 Defining `_meta.json` files with `private` properties](#431-defining-_metajson-files-with-private-properties)
+ - [4.3.2 Implementing the function](#432-implementing-the-function)
+ - [4.4 Running the script before building](#44-running-the-script-before-building)
+ - [5. Moving source files to `src` folder](#5-moving-source-files-to-src-folder)
+ - [6. Adding custom theme](#6-adding-custom-theme)
+ - [6.1 Copying the `nextra-theme-docs`](#61-copying-the-nextra-theme-docs)
+ - [6.2 Installing `TailwindCSS` and setting up `pnpm` workspace](#62-installing-tailwindcss-and-setting-up-pnpm-workspace)
+ - [6.3 Using `TailwindCSS` globally](#63-using-tailwindcss-globally)
+ - [7. Conditional rendering on components](#7-conditional-rendering-on-components)
+ - [7.1 With which methods can we do this?](#71-with-which-methods-can-we-do-this)
+ - [7.2 Using `useSession()`](#72-using-usesession)
+ - [7.3 Rendering links inside `navbar`](#73-rendering-links-inside-navbar)
+ - [7.4 Rendering links inside `sidebar`](#74-rendering-links-inside-sidebar)
+ - [7.4.1 Understanding how directory items are passed down to the `sidebar`](#741-understanding-how-directory-items-are-passed-down-to-the-sidebar)
+ - [7.4.2 Conditionally rendering links in `Menu` inside the `sidebar`](#742-conditionally-rendering-links-in-menu-inside-the-sidebar)
+- [Change theme](#change-theme)
+- [Zones](#zones)
+
+> [!TIP]
+>
+> Some of the info in these notes
+> can also be found in the
+> official `Nextra` docs:
+> [nextra.site/docs](https://nextra.site/docs)
+>
+> We recommend going through the docs
+> if you get stuck
+> or want a more in-depth understanding of the framework.
+
+When using `Nextra`,
+you _first_ have to choose:
+_either_ use a **`default` theme**
+***or*** **_customize_ your own**.
+
+The vast majority of people will use the **`default` theme**.
+However, if you need a _specific_ look & feel,
+you may have to create your own theme.
+We learned the hard way that it's _much_ easier
+to start with a custom theme
+than using a `default` one and attempt to change it afterwards ...
+see:
+[nextra#2926](https://github.com/shuding/nextra/issues/2926)
+
+For this demo,
+we'll start with the
+**`default` theme**
+and change it as needed.
+
+## 0. Start a new project ๐
+
+Before creating a project,
+first install the dependencies
+using
+[`pnpm`](https://pnpm.io/):
+
+```sh
+pnpm add next react react-dom nextra nextra-theme-docs
+```
+
+This will create a `package.json` file
+and install the dependencies under `/node_modules`.
+
+Next add the following scripts
+to `package.json`
+to run the app:
+
+```json
+"scripts": {
+ "dev": "next",
+ "build": "next build",
+ "start": "next start"
+},
+```
+
+Your `package.json` will look similar to:
+
+```json
+{
+ "scripts": {
+ "dev": "next",
+ "build": "next build",
+ "start": "next start"
+ },
+ "dependencies": {
+ "next": "^14.2.4",
+ "react": "^18.3.1",
+ "react-dom": "^18.3.1",
+ "nextra": "^2.13.4",
+ "nextra-theme-docs": "^2.13.4"
+ }
+}
+```
+
+Next, create a `Nextra` config file
+called
+`next.config.js`
+and add the following code to it:
+
+```js
+const withNextra = require('nextra')({
+ theme: 'nextra-theme-docs',
+ themeConfig: './theme.config.jsx',
+ defaultShowCopyCode: true
+})
+
+module.exports = withNextra()
+```
+
+This defines the global configuration for the project.
+e.g:
+`defaultShowCopyCode: true`,
+which will add a `copy` button to code snippets.
+
+Lastly, we need to create
+a corresponding
+`theme.config.jsx`
+file in project root directory.
+It is used to configure the `Nextra` site theme.
+Add the following code to it:
+
+```js
+import { DocsThemeConfig } from "nextra-theme-docs";
+
+const config: DocsThemeConfig = {
+ logo: Nextra Docs,
+ project: {
+ link: 'https://github.com/shuding/nextra'
+ }
+ }
+
+export default config
+```
+
+Save the file and continue.
+
+> [!TIP]
+>
+> Full theme config docs:
+> [nextra.site/docs/docs-theme](https://nextra.site/docs/docs-theme/theme-configuration).
+
+Given that
+`Nextra` is a **file-based system framework**
+(based on `Next.js`),
+we create docs
+under the `/pages` directory.
+Create a file with the path
+`pages/index.mdx`
+and type/paste the following markdown:
+
+```mdx
+# Welcome to our docs!
+
+Hello, world!
+```
+
+> [!NOTE]
+>
+> [`mdx`](https://mdxjs.com/)
+> files are markdown files
+> that allow you to write
+> `JSX`
+> markup.
+> Meaning you can import components
+> and embed them within your markdown files.
+
+Let's see the first page;
+Run:
+
+```sh
+pnpm run dev
+```
+
+and visit
+[localhost:3000](http://localhost:3000/)
+in your web browser
+You should see your page!
+
+
+ 
+
+
+Congrats!
+You've just set up your docs site!
+
+## 1. Organize Your Content ๐
+
+Now let's write some content!
+We are going to organize our documentation
+so it's easier to navigate.
+
+In `Nextra`,
+the site and page structure can be configured via
+[`_meta.json`](https://nextra.site/docs/guide/organize-files)
+files.
+These files will affect the layout of the theme,
+especially the sidebar/navigation bar.
+
+For example, the title and order of a page shown in the sidebar
+should be configured in the `_meta.json` file as key-value pairs.
+Create the following structure in your project.
+
+```sh
+pages
+|_ api_reference
+ |_ _meta.json
+ |_ about.mdx
+|_ _meta.json
+|_ about.mdx
+|_ contact.mdx
+|_ index.mdx
+```
+
+Define the pages `_meta.json`:
+
+```json
+{
+ "index": "My Homepage",
+ "contact": "Contact Us",
+ "api_reference": "API Reference",
+ "about": "About Us"
+}
+```
+
+And in the nested `_meta.json` file,
+inside `api_reference`.
+
+```json
+{
+ "about": "about"
+}
+```
+
+Group pages together in directories
+**to create _a hierarchy_** of pages.
+
+For a directory to have its own page,
+simply add an `index.mdx` file in the directory.
+If we need `api_reference` to have an introductory page,
+simply create the `index.mdx` file:
+
+```sh
+pages
+|_ api_reference
+ |_ _meta.json
+ |_ about.mdx
+ |_ index.mdx // added this
+|_ _meta.json
+|_ about.mdx
+|_ contact.mdx
+|_ index.mdx
+```
+
+Fill each `.mdx` file with content
+then run:
+`pnpm run dev`
+to see your pages organized!
+
+
+
+
+ 
+
+
+Awesome! ๐
+
+The basic docs site with organized content is working!
+
+## 2. Add Authentication ๐
+
+With the website working,
+we can add authentication
+to let `people` sign in
+and visit private pages.
+
+Using
+[`Auth.js`](https://authjs.dev/)
+to streamline the authentication process.
+This framework was previously working solely on `Next.js` projects,
+but this new `v5` release extends their compatibility to other frameworks.
+
+Let's add it to our project!
+
+> [!NOTE]
+>
+> At the time of writing,
+> only the `beta` version of `auth.js` is working.
+> We'll update this doc when a full stable release is announced.
+
+```sh
+pnpm add next-auth@beta
+```
+
+Next create the secret
+which is used by `auth.js` to encrypt token and e-mail verification hashes.
+
+Run:
+
+```sh
+npx auth secret
+```
+
+Your terminal will show this:
+
+```sh
+Need to install the following packages:
+auth@1.0.2
+Ok to proceed? (y) y
+
+Secret generated. Copy it to your .env/.env.local file (depending on framework):
+
+AUTH_SECRET=
+```
+
+Copy the secret and create a file called `.env.local`.
+e.g:
+
+```sh
+AUTH_SECRET="xYZIaxb3/4vWVFHO91ei850HX1c+4xt4LDg+HrEua2g="
+```
+
+`.env.local`
+is where all
+[environment variables](https://github.com/dwyl/learn-environment-variables)
+are stored for authentication.
+
+Now create the config files for `Auth.js` to work!
+Creating a file called `auth.ts` at the root
+and add the following code:
+
+```ts
+import NextAuth from "next-auth";
+
+export const { handlers, signIn, signOut, auth } = NextAuth({
+ providers: [],
+});
+```
+
+Then, create the following folders from the root of the project -
+`/app/api/auth/[...nextauth]/`.
+`Nextra` only works in the
+[Pages Router](https://nextjs.org/docs/pages).
+Authentication with `Auth.js` needs the
+[App Router](https://nextjs.org/docs/app) to work.
+For this, we need to create the folder hierarchy we've just mentioned.
+
+After creating the folders,
+create a file called `route.ts` inside `[...nextauth].
+
+```ts
+import { handlers } from "@/auth" // Referring to the auth.ts we just created
+export const { GET, POST } = handlers
+```
+
+Add a file called `middleware.ts` at the root of the project.
+This is to keep the session alive,
+this will update the session expiry every time its called.
+
+```ts
+export { auth as middleware } from "@/auth"
+```
+
+> [!NOTE]
+>
+> If your imports are complaining about
+> not being able to find the `@auth` module,
+> Create a `tsconfig.json` file at the root of the project
+> with the following code:
+
+```json
+{
+ "compilerOptions": {
+ "target": "es5",
+ "lib": ["dom", "dom.iterable", "esnext"],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "preserve",
+ "incremental": true,
+ "plugins": [
+ {
+ "name": "next"
+ }
+ ],
+ "paths": {
+ "@/*": ["./*"]
+ }
+ },
+ "include": [
+ "next-env.d.ts",
+ "**/*.ts",
+ "**/*.tsx",
+ ".next/types/**/*.ts",
+ "app/lib/placeholder-data.js",
+ "scripts/seed.js"
+ ],
+ "exclude": ["node_modules"]
+}
+```
+
+
+That's it!
+We're ready to go!
+
+
+### 2.1 Adding Github provider
+
+You can now decide how you are going to authenticate the users into your application.
+You can either:
+- choose an
+[`OAuth`](https://oauth.net/2/) provider
+delegated authentication where you delegate through a third party.
+- or you can set up your own
+[identity provider](https://www.cloudflare.com/en-gb/learning/access-management/what-is-an-identity-provider/)
+and take care of it yourself.
+
+We're going to choose the former, because it's easier.
+[`Auth.js` docs](https://authjs.dev/getting-started/authentication)
+explain it succinctly.
+
+> `OAuth` services spend significant amounts of money, time,
+> and engineering effort building abuse detection
+> (bot-protection, rate-limiting),
+> password management (password reset, credential stuffing, rotation),
+> data security (encryption/salting, strength validation), and much more.
+> It is likely that your application would benefit
+> from leveraging these battle-tested solutions
+> rather than try to rebuild them from scratch.
+
+Authenticate people through `GitHub`.
+
+Let's add it to our `providers` array inside `auth.ts`
+
+```ts
+import NextAuth from "next-auth";
+import GitHub from "next-auth/providers/github"
+
+export const { handlers, signIn, signOut, auth } = NextAuth({
+ providers: [GitHub],
+});
+
+```
+
+Next, create an **`OAuth` app**.
+Navigate to
+[github.com/settings/developers](https://github.com/settings/developers)
+and click on `OAuth Apps`
+and click on `New OAuth App`.
+
+
+ 
+
+
+Fill out the information.
+The default callback URL will be of the form of
+`[origin]/api/auth/callback/[provider]`.
+While developing, you may use `localhost` as the `origin`.
+e.g:
+```sh
+http://localhost:3000/api/auth/callback/github
+```
+
+In production it will be something like:
+
+```sh
+https://docs.company.com/api/auth/callback/github
+```
+
+
+ 
+
+
+After completing the form,
+you will be redirected to the page of your newly created `OAuth` app.
+Click on `Generate a new client secret`.
+
+
+ 
+
+
+You will be shown the secret of the new app.
+Do not close the page, you will need to copy this `secret`
+and the shown `client ID.`
+
+
+ 
+
+
+In your `.env.local` file,
+add these two copied strings, like so.
+
+```sh
+AUTH_SECRET=
+
+AUTH_GITHUB_ID=
+AUTH_GITHUB_SECRET=
+```
+
+And that's all the configuration we need!
+Now it's time to authenticate people into our app!
+
+
+### 2.2 Letting people `Sign In` and `Sign Out`
+
+With all the configuration out of the way,
+it's time to a way for people to **sign in** and **sign out** of our Nextra website.
+
+Before continuing,
+let's change our site's structure a little bit.
+Make it like so.
+
+```
+pages
+|_ reference_api // yes, change from 'api_reference' to 'reference_api'
+ |_ mega_private // add this new folder
+ |_ _meta.json
+ |_ hello.mdx
+ |_ _meta.json
+ |_ about.mdx
+ |_ mega_private.mdx // This is the index page of `mega_private` that will show on the sidebar. Write whatever.
+ |_ users.mdx
+|_ _meta.json
+|_ about.mdx
+|_ api_reference.mdx
+|_ contact.mdx
+|_ index.mdx
+```
+
+> [!IMPORTANT]
+>
+> Change the root `_meta.json` file pertaining to `"api_reference"`
+> to `"reference_api"`, and the folder as well.
+>
+> This is important because we are going to have a middleware
+> that is going to match routes to perform authorization checks.
+> `Next.js` projects usually have APIs under `/api`,
+> which means the middleware was not going to perform verifications on anything
+> under `api`.
+
+Create a new folder `mega_private` inside `api_reference`.
+We'll use this later.
+You can write whatever you want in it.
+Keep the `_meta.json` inside `mega_private` simple, like so.
+
+```json
+{
+ "hello": "Hello page"
+}
+```
+
+Great!
+
+`next-auth` provides a set of built-in pages
+for people to go through their authentication journey
+(sign in, sign up, sign out, error, etc...).
+[Although you can customize your own pages](https://authjs.dev/guides/pages/signin),
+we are going to leverage these built-in pages
+to keep the tutorial simple.
+
+To allow people to sign in,
+let's create a component to be shown in `pages/index.mdx`,
+the root page of the site.
+
+For this, create a folder called `components` on the root of the project.
+Inside of `components`, create `LoginOrUserInfo`,
+and inside this one create with the path:
+`components/LoginOrUserInfo/index.tsx`
+and code:
+
+```ts
+import { signOut, signIn } from "next-auth/react";
+import { DefaultSession } from "next-auth";
+
+export function LoginOrUserInfo({ session } : Readonly<{session: DefaultSession}>) {
+ if (session?.user) {
+ return (
+
+
+ Welcome {session.user.name}
+ {" "}
+
+
+
+ );
+ } else {
+ return ;
+ }
+}
+```
+
+This exports a function `LoginOrUserInfo`
+that receives `Session` object (from `next-auth`).
+Inside this component, what we do is really simple:
+show his name and a `SignOut` button if they are logged in;
+otherwise, show a button to `SignIn`.
+
+Leveraging both `signIn` and `signOut` functions from `next-auth`.
+
+> [!WARNING]
+>
+> By creating these nested folders,
+> we have to update the `tsconfig.json` file to encompass
+> files that are nested on more than two levels.
+>
+> ```json
+> "include": [
+> "next-env.d.ts",
+> "*/**/*.ts", // add this line
+> "**/*.ts",
+> "**/*.tsx",
+> ".next/types/**/*.ts",
+> "app/lib/placeholder-data.js",
+> "scripts/seed.js"
+> ],
+> ```
+
+Now let's use our newly created component.
+Go to `pages/index.mdx` and add the following code to the top.
+
+```mdx
+import { auth } from "@/auth.ts"
+import { useData } from 'nextra/data'
+import Link from 'next/link'
+import { signOut } from "next-auth/react"
+import { LoginOrUserInfo } from "@/components/LoginOrUserInfo"
+
+export async function getServerSideProps(ctx) {
+ const session = await auth(ctx)
+
+return {
+ props: {
+ // We add an `ssg` field to the page props,
+ // which will be provided to the Nextra `useData` hook.
+ ssg: {
+ session
+ }
+ }
+ }
+}
+
+export const Info = () => {
+ // Get the data from SSG, and render it as a component.
+ const { session } = useData()
+ return
+```
+
+We are using [`getServerSideProps` ](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-server-side-props)
+to fetch the session from the `auth` function from `next-auth`.
+For more information about this inside `Nextra`,
+visit https://nextra.site/docs/guide/ssg.
+
+We need to return the session inside an object `props`
+and adding a named property called `ssg`
+with the data we want to send over the components we want to display.
+`Nextra` retrieves this data using the `useData()` hook.
+
+In the `Info` component, we fetch the `session` object
+from the `auth` and pass it to the component
+we've created ``.
+
+All that's left is using this component in our `.mdx` file.
+Simply add `` (the component we've created inside `.mdx`)
+wherever you want in the page1
+
+If you run the application, you should be able to sign in and sign out!
+
+
+ 
+ 
+ 
+
+
+We now have access to [`JWT` tokens](https://jwt.io/introduction) in our application,
+where `GitHub`'s `OAuth` provider is providing them for us.
+
+Now let's start using it to start protecting routes!
+
+
+## 3. Protecting routes
+
+We now have a basic authentication flow in our site,
+with `GitHub` providing and managing the tokens for our application for us.
+It's in our interest to restrict certain routes to specific users
+with specific roles if we ever want to make our awesome documentation site
+*available to different clients*.
+
+
+### 3.1 A word about `middleware.ts`
+
+Normally, when developing applications that follow the normal
+`Frontend -> Backend -> Database` convention,
+you usually want to have security measures
+**as close to the data as possible**.
+
+[With `React Server Components` being introduced in `Next.js`](https://nextjs.org/docs/app/building-your-application/rendering/server-components),
+the line between server and client gets blurred.
+Data handling is paramount in understanding where information is processed
+and subsequently made available.
+So we always have to be careful to know
+how authentication and how protecting routes is implemented
+and *where* it is processed,
+so it's not subject to malicious actors.
+
+
+> [!NOTE]
+>
+> To learn more about Data Access Layers,
+> please visit https://x.com/delba_oliveira/status/1800921612105011284
+> and https://nextjs.org/blog/security-nextjs-server-components-actions.
+> These links provide great insights on how to implement a Data Access Layer
+> to better encapsulate your data and minimize security pitfalls.
+
+For this purpose,
+because `Nextra` statically generates pages,
+we are going to be using [**`middleware`**](https://nextjs.org/docs/pages/building-your-application/routing/middleware)
+to protect the routes.
+[`next-auth`](https://authjs.dev/getting-started/session-management/protecting?framework=express#api-routes)
+warns people to
+**on middleware exclusively for authorization and to always ensure that the session is verified as close to your data fetching as possible.**
+While that is true
+(and a reiteration of what was aforementioned),
+protecting the routes in our application
+through `middleware`
+is optimistically secure enough
+(as it runs on the server-side),
+as it runs on every request,
+including prefetched routes.
+Additionally, [`Next.js` recommends doing so](https://nextjs.org/docs/pages/building-your-application/authentication#protecting-routes-with-middleware).
+
+> "This is important for keeping areas like the user dashboard protected while having other pages like marketing pages be public.
+> It's recommended to apply Middleware across all routes and specify exclusions for public access.
+
+
+### 3.2 Adding `middleware.ts` logic
+
+As per `Next.js`'s convention,
+to add this middleware,
+we need to create a `middleware.ts` file at the root of the project.
+
+Create it and add the following code to it:
+
+```ts
+// middleware.ts
+
+"server only";
+
+import { auth } from "@/auth";
+import { NextResponse } from "next/server";
+
+// !!!! DO NOT CHANGE THE NAME OF THE VARIABLE !!!!
+const privateRoutesMap: any = {};
+
+export default auth(async (req, ctx) => {
+ const currentPath = req.nextUrl.pathname;
+ const isProtectedRoute = currentPath in privateRoutesMap
+
+ if(isProtectedRoute) {
+ // Check for valid session
+ const session = req.auth
+
+ // Redirect unauthed users
+ if(!session?.user || !session.user.role) {
+ return NextResponse.redirect(new URL('/api/auth/signin', req.nextUrl))
+ }
+
+ // Redirect users that don't have the necessary roles
+ const neededRolesForPath = privateRoutesMap[currentPath]
+ if(!(session.user.role && neededRolesForPath.includes(session.user.role))) {
+ return NextResponse.redirect(new URL('/api/auth/signin', req.nextUrl))
+ }
+ }
+
+ return NextResponse.next()
+});
+
+export const config = {
+ matcher: [
+ /*
+ * Match all request paths except for the ones starting with:
+ * - api (API routes)
+ * - _next/static (static files)
+ * - _next/image (image optimization files)
+ * - favicon.ico (favicon file)
+ */
+ '/((?!api|_next/static|_next/image|favicon.ico).*)',
+ ],
+}
+
+```
+
+Let's break down what we just wrote:
+
+- **`privateRoutesMap`** is an object/map that will have the **path** as `key`
+and the **array of roles needed to access the path** as `value`.
+This variable will be changed on build-time,
+so do not change its name!
+- we export **`auth`** as default from `middleware.ts`.
+This function is called before every route server-side.
+Inside it, we check the path and the session cookie.
+With these, we can know *if the route is protected* or not.
+If it is, we check if the person can access it with the given role.
+If any of these conditions fail,
+the person is redirected to the Sign In page.
+- we also export a **`config`** object,
+with a `matcher` property.
+We use [`RegEx`](https://regexr.com/) to configure which paths we want the middleware to run on.
+
+> [!NOTE]
+>
+> Your `Typescript` compiler may be complaining
+> because `role` is not a property inside `user`.
+> Don't worry, we'll fix this now.
+
+
+### 3.3 Configuring `auth.ts`
+
+`middleware.ts` assumes the `JWT` token to have a role
+in order to do role-based authorization.
+For it to have access to it
+(and throughout the whole application),
+we ought to head over to `auth.ts`
+and do additional configuration.
+
+Open `auth.ts` and change it the following.
+
+```ts
+// auth.ts
+
+export const { handlers, signIn, signOut, auth } = NextAuth({
+ providers: [
+ GitHub({
+ profile(profile) {
+ // GitHub's OAuth apps don't allow you to define roles.
+ // So `profile` here doesn't have a `role` property.
+ // But on other providers, you'd add the role here through it.
+ return {
+ id: profile.id.toString(),
+ name: profile.name ?? profile.login,
+ email: profile.email,
+ image: profile.avatar_url,
+ role: "user",
+ };
+ },
+ }),
+ ],
+ callbacks: {
+ jwt({ token, user, account, profile }) {
+ // Normally, it would be like this
+ // if(user) return {...token, role: token.role}
+ // return token
+
+ // But because Github's provider is not passing the role
+ // (it should, according to https://authjs.dev/guides/role-based-access-control#with-jwt -
+ // maybe it's because v5 is still in beta), we're just gonna append it every time
+ return {...token, role: "user"}
+ },
+ session({ session, token }) {
+ session.user.role = token.role;
+ return session;
+ },
+ },
+});
+```
+
+As usual, let's break it down!
+
+- the `GitHub` provider accepts a **`profile()`** callback.
+In this callback, we receive a `Profile` returned by the `OAuth` provider
+(in our case, it's `GitHub`).
+We can return a subset using the profile's information
+to **define user's information in our application**.
+By default, it returns the
+`id`, `email`, `name`, `image`,
+but we can add more.
+That's what we did, by adding the **`role`** property.
+
+> [!NOTE]
+>
+> If you're using a custom provider,
+> it is your responsibility to return the role so you can capture it in
+> your `Next.js`/`Nextra` application.
+
+- we defined **`callbacks`** to add the role to our `JWT` tokens
+and `session` cookies.
+In order, the `jwt` callback receives the user information we've defined earlier.
+We append the `role` to the token.
+Afterwards, the `session` callback is invoked,
+where we use the `role` property we've just appended to the `token`
+and add it to the `session` cookie.
+
+> [!NOTE]
+>
+> In our code, we hardcode it every time.
+> It is because, at the time of writing,
+> `next-auth` is releasing a `v5`,
+> which has some bugs,
+> including the `GitHub` provider not properly downstreaming the user
+> to the `jwt` and `session` callbacks.
+> They receive the `user` as `undefined`.
+>
+> Unfortunately, this not an isolated occurrence.
+> https://stackoverflow.com/questions/76986309/nextauth-nextjs-13-unable-to-add-user-role
+> describes our exact scenario
+> and doesn't have an answer ๐.
+>
+> Here are a few more examples.
+> Hopefully it will be resolved in time:
+> - https://github.com/nextauthjs/next-auth/issues/9836
+> - https://github.com/nextauthjs/next-auth/discussions/9609
+> - https://stackoverflow.com/questions/72073321/why-did-user-object-is-undefined-in-nextauth-session-callback
+> - https://github.com/nextauthjs/next-auth/discussions/8456
+>
+> If you're using a custom provider,
+> it seems this is unlikely to happen to you.
+> In the links above,
+> people found solutions using custom providers
+> and not the in-built ones, like we are using in this demo.
+
+
+> [!IMPORTANT]
+>
+> To make the experience better for the user,
+> we can implement a **refresh token rotation system**,
+> where once a token expires,
+> the application automatically refreshes it instead of asking the user to sign in again.
+>
+> Read https://authjs.dev/guides/refresh-token-rotation to implement this with `next-auth`.
+
+But that's not all!
+Because we are effectively
+*extending* the properties of the `User`,
+we can [**augment it through types**](https://authjs.dev/getting-started/typescript#module-augmentation),
+so `Typescript` doesn't complain about `role`
+being an `undefined` property.
+
+In the same `auth.ts` file,
+add the following code at the top.
+
+```ts
+import GitHub from "next-auth/providers/github";
+import NextAuth, { type DefaultSession } from "next-auth";
+// we don't use these but we need to import something so we can override the interface
+import { DefaultJWT } from "next-auth/jwt";
+import { AdapterSession } from 'next-auth/adapters';
+
+// We need to add the role to the JWT inside `NextAuth` below, so the `middleware.ts` can have access to it.
+// The problem is that it wasn't added this `role` custom field, even if we defined it in `auth.ts`.
+// Apparently, the problem is with the types of `next-auth`, which we need to redefine.
+// See https://stackoverflow.com/questions/74425533/property-role-does-not-exist-on-type-user-adapteruser-in-nextauth
+// and see https://authjs.dev/getting-started/typescript#module-augmentation.
+
+declare module "next-auth" {
+ interface Session extends DefaultSession {
+ /**
+ * By default, TypeScript merges new interface properties and overwrites existing ones.
+ * In this case, the default session user properties will be overwritten,
+ * with the new ones defined above. To keep the default session user properties,
+ * we need to add them back into the newly declared interface.
+ */
+ user: DefaultSession["user"] & {
+ role?: string;
+ };
+ }
+
+ interface User {
+ // Additional properties here:
+ role?: string;
+ }
+}
+
+declare module "next-auth/adapters" {
+ interface AdapterUser {
+ // Additional properties here:
+ role?: string;
+ }
+}
+
+declare module "next-auth/jwt" {
+ interface JWT {
+ role?: string;
+ }
+}
+```
+
+And that's it! ๐
+Give yourself a pat on the back!
+
+Now that we have the authentication and authorization set up,
+it's time to *finally use it*.
+
+
+## 4. Generating private routes
+
+As you may have noticed by now,
+`Nextra` statically generates the page for you
+following the structure and the `_meta.json` files
+that you define in your project.
+These changes are then reflected in your navbar and sidebar.
+
+However, there is *no way for us to define private routes*
+and **use them at build-time**,
+like you do when generating the pages with `Nextra`.
+Unfortunately, `Nextra` doesn't have this feature in place,
+and authentication is not something they had in mind to implement
+for a framework that was primarily meant for public-facing documentation.
+
+*However*, it is possible to do this,
+considering what was discussed in
+[3.1 A word about `middleware.ts`](#31-a-word-about-middlewarets),
+_as long as we have access to the private routes at **build-time**_.
+
+To accomplish this, we're using [`ts-morph`](https://ts-morph.com/),
+a package that will allow us to manipulate Typescript source files.
+We will create a script with `ts-morph` that manipulates the `const privateRoutesMap` inside `middleware.ts`.
+This script will populate the `const` with all the private routes
+and the needed roles to access them.
+
+Let's crack on!
+
+
+### 4.1 Installing `ts-morph` and setup
+
+Install `ts-morph`, [`ts-node`](https://www.npmjs.com/package/ts-node) (to run the script we're implementing)
+and [`fast-glob`](https://www.npmjs.com/package/fast-glob)
+(to traverse the file system).
+
+```sh
+pnpm add ts-morph ts-node fast-glob
+```
+
+After installing these dependencies,
+we will have to adjust our `tsconfig.json` file
+so we can run our script independently.
+Below the `exclude` property, in the last line,
+add the following piece of code.
+
+```json
+ "exclude": ["node_modules"],
+
+ // These are only used by `ts-node` to run the script that generates the private routes.
+ // These options are overrides used only by ts-node, same as the --compilerOptions flag and the TS_NODE_COMPILER_OPTIONS environment variable
+ "ts-node": {
+ "compilerOptions": {
+ "module": "commonjs"
+ }
+ },
+```
+
+Great!
+Let's start implementing our script now.
+
+
+### 4.2 Creating `generatePrivateRoutes.ts`
+
+In the root of the project,
+create a file called `generatePrivateRoutes.ts`.
+Add the following code.
+
+```ts
+import { Project } from "ts-morph";
+import path from "path";
+import fs from "fs";
+import { globSync } from "fast-glob";
+
+// - - - - - - - - - - - - - - - - - - - - - - -
+// `middleware.ts` is changed by executing the code below.
+
+const CONST_VARIABLE_NAME = "privateRoutesMap"; // Name of the constant inside `middleware.ts` to be manipulated
+const DIRECTORY = "pages"; // Directory to look for the routes (should be `pages`, according to Nextra's file system)
+
+export function changeMiddleware() {
+
+ // Get private routes
+ const pagesDir = path.join(__dirname, DIRECTORY);
+ const privateRoutes = getPrivateRoutes(pagesDir);
+
+ // Initialize the project and source file
+ const project = new Project();
+ const sourceFile = project.addSourceFileAtPath(path.resolve(__dirname, "middleware.ts"));
+
+ // Find the variable to replace and change it's declaration
+ const variable = sourceFile.getVariableDeclaration(CONST_VARIABLE_NAME);
+ if (variable) {
+ variable.setInitializer(JSON.stringify(privateRoutes));
+ sourceFile.saveSync();
+ } else {
+ console.error("Variable not found in `middleware.ts`. File wasn't changed.");
+ }
+}
+
+export default {
+ changeMiddleware: () => changeMiddleware()
+}
+```
+
+The code is fairly simple.
+We get the private routes by calling a function called `getPrivateRoutes()`
+(which we will implement shortly).
+Then, we find the `middleware.ts` file
+and find the variable we want to change.
+If we do find it, we change its initialization
+to the private routes map we retrieved earlier.
+Otherwise, we log an error.
+
+Now, it's time to add the function
+that will *retrieve the private routes*!
+
+
+### 4.3 Implementing private route retrieval function
+
+Our function `getPrivateRoutes` will need to recursively iterate
+over a given folder directory and find a way to know which routes are private.
+As of now, there's no way of doing so.
+
+That's why we're going
+**to define a new property inside `_meta.json` files**.
+
+
+#### 4.3.1 Defining `_meta.json` files with `private` properties
+
+We need to tell our function which pages/routes are private.
+To do this, we are going to use the `_meta.json` files
+that come with `Nextra`.
+
+To achieve this,
+we are going to allow people to declare a route as private
+by adding a **`private`** property to a route defined in the respective `_meta.json`.
+
+```json
+// pages/_meta.json
+{
+ "index": {
+ "title": "Homepage",
+ "type": "page",
+ "display": "hidden"
+ },
+ "reference_api": {
+ "title": "API Reference",
+ "type": "page",
+ "private": { // We add this property to make `reference_api` private
+ "private": true,
+ "roles": ["user"]
+ }
+ },
+ "about": {
+ "title": "About Us",
+ "type": "page"
+ },
+ "contact": {
+ "title": "Contact Us",
+ "type": "page"
+ },
+ "github_link": {
+ "title": "Github",
+ "href": "https://github.com/shuding/nextra",
+ "newWindow": true,
+ "display": "hidden"
+ }
+}
+```
+
+As you can see, we've added a property called **`private`**
+to the `reference_api` route,
+where we define if it's private or not by boolean in the `private` property
+and where we define the roles that can access it
+in the `roles` property.
+
+Alternatively, people can define private routes by simply
+passing `"private": true`, instead of passing an object.
+In these cases, the `roles` empty will default to an empty array,
+
+```json
+ "reference_api": {
+ "title": "API Reference",
+ "type": "page",
+ "private": true // Simpler version
+ },
+```
+
+We'll take into account both of these scenarios.
+
+
+#### 4.3.2 Implementing the function
+
+Okay, now let's start coding our function!
+Inside `generatePrivateRoutes.ts`,
+add this function above the `ts-morph` code
+we've written earlier.
+
+```ts
+// Types for the `_meta.json` structure
+type PrivateInfo = {
+ private: boolean;
+ roles?: string[];
+};
+
+type MetaJson = {
+ [key: string]: string | any | PrivateInfo;
+};
+
+type PrivateRoutes = {
+ [key: string]: string[];
+};
+
+/**
+ * This function looks at the file system under a path and goes through each `_meta.json` looking for private routes recursively.
+ * It is expecting the `_meta.json` values of keys to have a property called "private" to consider the route as private for specific roles.
+ * If a parent is private, all the children are private as well. The children inherit the roles of their direct parent.
+ * @param pagesDir path to recursively look for.
+ * @returns map of private routes as key and array of roles that are permitted to access the route.
+ */
+function getPrivateRoutes(pagesDir: string): PrivateRoutes {
+ let privateRoutes: PrivateRoutes = {};
+
+ // Find all _meta.json files recursively
+ const metaFiles = globSync(path.join(pagesDir, "**/_meta.json"));
+
+ // Variable to keep track if parent is private on nested routes and its role
+ const rootPrivateSettings: { [key: string]: { private: boolean; roles: string[] } } = {};
+
+ // Iterate over the found meta files
+ for (const file of metaFiles) {
+ // Get the path of file and read it
+ const dir = path.dirname(file);
+ const metaJson: MetaJson = JSON.parse(fs.readFileSync(file, "utf-8"));
+
+ // Iterate over the key/value pairs of the "_meta.json" file
+ for (const [key, meta] of Object.entries(metaJson)) {
+ const route = path.join(dir, key).replace(pagesDir, "").replace(/\\/g, "/");
+
+ // Check if the current meta has a "private" property
+ if (meta.private !== undefined) {
+ if (typeof meta.private === "boolean") {
+ if (meta.private) {
+ privateRoutes[route] = [];
+ rootPrivateSettings[dir] = { private: true, roles: [] };
+ }
+ }
+ // If the "private" property is an object with possible roles
+ else if (meta.private.private === true) {
+ const roles = meta.private.roles ? meta.private.roles : [];
+ privateRoutes[route] = roles;
+ rootPrivateSettings[dir] = { private: true, roles: roles };
+ }
+ } else {
+ // Check if the parent folder is private and inherit roles
+ const parentDir = path.resolve(dir, "..");
+ if (rootPrivateSettings[parentDir] && rootPrivateSettings[parentDir].private) {
+ const parentRoles = rootPrivateSettings[parentDir].roles;
+ privateRoutes[route] = parentRoles;
+ }
+ }
+ }
+ }
+
+ // Now let's just do a second pass to clean-up possible unwanted/invalid routes
+ for (const route of Object.keys(privateRoutes)) {
+ const fullPath = path.join(pagesDir, route);
+ const lastSegment = route.split("/").pop();
+
+ // Remove separators or any route that doesn't correspond to an existing file/directory
+ if (lastSegment === "---") {
+ delete privateRoutes[route];
+ continue;
+ }
+
+ // Check for the existence of .mdx file
+ const mdxPath = `${fullPath}.mdx`;
+ if (!fs.existsSync(fullPath) && !fs.existsSync(mdxPath)) {
+ delete privateRoutes[route];
+ }
+ }
+
+ return privateRoutes;
+}
+```
+
+Whoa, that's a lot!
+The code is fairly documented so you can follow along easier.
+But the gist of it is:
+- we use `fast-glob` to find all the `_meta.json` files recursively.
+- we iterate over the `_meta.json` files.
+ - in each `_meta.json`, we look over the key-value pairs to construct the route.
+ - in each key-value, we check for the `private` property and resolve its boolean.
+ - while iterating, we keep track of the routes and check if the parent is also private. If the parent is private, the child must be private too. It also inherits the direct parent's roles.
+- after iteration, we do a second pass to clean-up possible invalid routes.
+- we return a map of `private route` as **key** and `roles array` as **value**.
+
+And that's it!
+
+
+### 4.4 Running the script before building
+
+Now that we have our handy-dandy script ready,
+we need to make sure it always gets executed before running our application,
+whether it is being built for production
+or compiling to be running on `localhost`.
+
+To do this, we only need to change our `package.json` file.
+Head over there and change the scripts, like so:
+
+```json
+ "scripts": {
+ "private-route-gen": "ts-node -e \"import gen from './src/generatePrivateRoutes'; gen.changeMiddleware()\"",
+ "dev": "npm run private-route-gen && next",
+ "prebuild": "npm run private-route-gen",
+ "build": "next build",
+ "start": "next start"
+ },
+```
+
+We've created a `private-route-gen`
+that uses `ts-node` to run our script.
+This newly added script is executed
+when running `pnpm run dev` (running the app locally)
+and `pnpm run build`.
+[We've added it to the `prebuild` script](https://kontent.ai/blog/how-to-run-scripts-before-every-build-on-next-js/)
+so it executes before production builds.
+
+And that's it!
+Now every time you run your application,
+we are sure that the private routes are correctly materialized!
+
+Hurray! ๐
+
+
+> [!NOTE]
+>
+> You may get an error when building the project saying:
+>
+> ```
+> Error validating _meta.json file for "reference_api" property.
+> Unrecognized key(s) in object: 'private'
+> ```
+>
+> This is expected, since `Nextra` doesn't know what the `private` property is.
+> This doesn't affect the performance of the application,
+> it's simply a warning.
+
+
+## 5. Moving source files to `src` folder
+
+Before proceeding, let's do some cleaning up ๐งน.
+Right now, we have some source files
+(like `auth.ts`, `middleware.ts`, `generatePrivateRoutes.ts`)
+mixed with several configuration files at root level.
+
+Luckily for us, `Next.js` supports adding a `src` folder
+so we can keep the root directory focused on configuration files
+and the `src` folder to source files.
+
+Let's move our source code to a `src` folder!
+Start by creating it at root level.
+Then, move the following items into it:
+- the `app` folder.
+- the `components` folder.
+- the `pages` folder.
+- `auth.ts`, `middleware.ts` and `generatePrivateRoutes.ts` files.
+
+Now we have to change some imports.
+Check the following changes in each file so everything works again!
+
+```ts
+// src/pages/index.mdx
+import { auth } from "@/src/auth.ts" // changed from `@/auth.ts`
+import { useData } from 'nextra/data'
+import Link from 'next/link'
+import { signOut } from "next-auth/react"
+import LoginOrUserInfo from "@/src/components/LoginOrUserInfo" // changed from `@/components/LoginOrUserInfo`
+```
+
+```ts
+// src/middleware.ts
+"server only";
+
+import { auth } from "@/src/auth"; // changed from `@/auth.ts`
+import { NextResponse } from "next/server";
+```
+
+```ts
+// tests/unit/LoginOrUserInfo.test.tsx
+import { render, screen } from "@testing-library/react";
+import LoginOrUserInfo from "@/src/components/LoginOrUserInfo"; // changed from `@/components/LoginOrUserInfo`
+import { DefaultSession } from "next-auth";
+import { signOut, signIn } from "next-auth/react";
+```
+
+```json
+// package.json
+"private-route-gen": "ts-node src/generatePrivateRoutes.ts",
+```
+
+And you're sorted!
+We now have all our source files inside `src`,
+the tests inside `tests`,
+and all the configuration files at root level.
+
+
+## 6. Adding custom theme
+
+Now that we've protected some routes through the `middleware.ts` file,
+we need to go a bit further.
+It doesn't make sense for public people to see the private routes,
+either be it on the **sidebar** or on the **navbar**.
+
+For this, we can go about this with two options:
+
+1. we **customize the default theme** through `theme.config.jsx` (https://nextra.site/docs/docs-theme/theme-configuration#customize-the-navbar),
+where we check [each sidebar title and hide it](https://nextra.site/docs/docs-theme/theme-configuration#docs-repository)
+and [override the whole navbar](https://nextra.site/docs/docs-theme/theme-configuration#customize-the-navbar).
+
+2. use the code from the [`nextra-theme-docs`](https://github.com/shuding/nextra/tree/main/packages/nextra-theme-docs)
+to keep the default theme, use it as a `custom-theme` in `theme.config.jsx`
+and try to conditionally render each link according to the person's role.
+
+Although you can go with `Option 1` for simplicity sake,
+we are going with `Option 2` for three main reasons:
+
+- we want to keep the same look n' feel of the application as it stands.
+- we don't want to re-implement and waste the time trying to do so.
+- we want to have access to the `private` property we've defined inside `_meta.json` files,
+which can only be made through augmenting the types of the `nextra-docs-theme` source code.
+
+With this in mind, let's do this!
+
+
+### 6.1 Copying the `nextra-theme-docs`
+
+
+Download the directory from https://github.com/dwyl/nextra-demo/tree/34a6327e00b941b50dffdbbed99ab6bf294511a4/theme.
+This directory is a version of [`nextra-theme-docs`](https://github.com/shuding/nextra/tree/main/packages/nextra-theme-docs)
+**with a few modifications** (they are explained in the `README.md` inside the directory).
+
+Long story short, the differences are:
+- we've imported some [`nextra` components](https://github.com/shuding/nextra/tree/main/packages/nextra/src/components)
+from the original package and placed it inside the theme.
+- moved some code from `src/constants.tsx` to `src/contexts/config.tsx`.
+This is because, as is, the code threw a
+`ReferenceError: Cannot access 'DEFAULT_THEME' before initialization` error.
+- removed `tailwind.config.js` and `postcss.config.js`.
+We'll be using these on the **root of the project** instead.
+
+After downloading this directory,
+put all of the downloaded code inside a new directory called `theme`.
+
+
+### 6.2 Installing `TailwindCSS` and setting up `pnpm` workspace
+
+For this to work,
+we'll have to install `TailwindCSS` on our project.
+This is what the custom theme depends on to properly render their components.
+
+For this, open the terminal and type `pnpm install tailwindcss postcss autoprefixer`.
+
+Next up, let's create two files:
+`tailwind.config.js` and `postcss.config.js`.
+These two files are from the original theme.
+
+```js
+// tailwind.config.js
+
+const colors = require('tailwindcss/colors')
+
+const makePrimaryColor =
+ l =>
+ ({ opacityValue }) => {
+ return (
+ `hsl(var(--nextra-primary-hue) var(--nextra-primary-saturation) ${l}%` +
+ (opacityValue ? ` / ${opacityValue})` : ')')
+ )
+ }
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+ prefix: 'nx-',
+ content: [
+ './theme/src/**/*.tsx',
+ './theme/src/nextra_icons/*.tsx',
+ './theme/src/nextra_components/*.tsx'
+ ],
+ theme: {
+ screens: {
+ sm: '640px',
+ md: '768px',
+ lg: '1024px',
+ xl: '1280px',
+ '2xl': '1536px'
+ },
+ fontSize: {
+ xs: '.75rem',
+ sm: '.875rem',
+ base: '1rem',
+ lg: '1.125rem',
+ xl: '1.25rem',
+ '2xl': '1.5rem',
+ '3xl': '1.875rem',
+ '4xl': '2.25rem',
+ '5xl': '3rem',
+ '6xl': '4rem'
+ },
+ letterSpacing: {
+ tight: '-0.015em'
+ },
+ colors: {
+ transparent: 'transparent',
+ current: 'currentColor',
+ black: '#000',
+ white: '#fff',
+ gray: colors.gray,
+ slate: colors.slate,
+ neutral: colors.neutral,
+ red: colors.red,
+ orange: colors.orange,
+ blue: colors.blue,
+ yellow: colors.yellow,
+ primary: {
+ 50: makePrimaryColor(97),
+ 100: makePrimaryColor(94),
+ 200: makePrimaryColor(86),
+ 300: makePrimaryColor(77),
+ 400: makePrimaryColor(66),
+ 500: makePrimaryColor(50),
+ 600: makePrimaryColor(45),
+ 700: makePrimaryColor(39),
+ 750: makePrimaryColor(35),
+ 800: makePrimaryColor(32),
+ 900: makePrimaryColor(24)
+ }
+ },
+ extend: {
+ colors: {
+ dark: '#111'
+ }
+ }
+ },
+ darkMode: ['class', 'html[class~="dark"]']
+}
+```
+
+```js
+// postcss.config.js
+/** @type {import('postcss').Postcss} */
+module.exports = {
+ plugins: {
+ 'postcss-import': {},
+ 'tailwindcss/nesting': {},
+ tailwindcss: {},
+ 'postcss-lightningcss': {
+ browsers: '>= .25%'
+ }
+ }
+}
+```
+
+And that's it for the `TailwindCSS` part of things!
+Now, because our `theme` directory has its own set of dependencies,
+we need to tell our root project that information!
+We want it to install and use its dependencies.
+For this, we leverage [**`pnpm` Workspaces**](https://pnpm.io/workspaces)
+to install and update dependencies in a single `pnpm install` command!
+
+For this, we have to:
+- give our root project's workspace a name.
+We can do this by going to `package.json` and adding the line
+`"name": "nextra"` on top.
+- create a `pnpm-workspace.yaml` file.
+
+```yaml
+packages:
+ - '.'
+ - 'theme'
+```
+
+
+### 6.3 Using `TailwindCSS` globally
+
+Now that we've installed `TailwindCSS`,
+let's *use it* in our application!
+
+For our theme to work, we need to create a `.css` file
+and import it in our `Pages Router` so it is used throughout our application pages.
+To do this,
+create a file inside `src` - `src/globals.css`.
+
+```css
+/* Use the theme's styles CSS file */
+@import "../theme/css/styles.css"
+```
+
+Easy enough, right?
+We are simply using the `theme`'s styles in our own application's styles!
+Now we just need *to use it in our application*.
+To do this,
+we are going to be using a [**custom app component**](https://nextjs.org/docs/pages/building-your-application/routing/custom-app),
+which is called to initialize pages.
+We are going to override it to inject our styles.
+
+Inside `src/pages`, create a file called `_app.tsx`.
+
+```tsx
+// These styles apply to every route in the application
+import '@/src/globals.css'
+import type { AppProps } from 'next/app'
+
+export default function App({ Component, pageProps }: AppProps) {
+ return
+}
+```
+
+And that's it!
+
+The *very last thing we need to do*,
+is to **tell `Nextra` we want to use our custom theme**.
+For this, simply head over to `next.config.js`
+and change the `theme` property
+to the directory of our newly created `theme` directory.
+
+```js
+const withNextra = require("nextra")({
+ theme: "./theme/src/index.tsx", // change here
+ themeConfig: "./theme.config.jsx",
+ defaultShowCopyCode: true
+});
+
+module.exports = withNextra();
+```
+
+If you run `pnpm run dev`, you should be able to see the application running as before!
+
+
+## 7. Conditional rendering on components
+
+Now that we have our custom theme properly setup and added to our application,
+we now have the opportunity to do whatever we want with the components.
+In our case, it is *extremely useful*
+to **conditionally render links of protected routes according to the logged user**.
+
+
+### 7.1 With which methods can we do this?
+
+`auth.js` provides us a few ways of authenticating people
+and getting their session.
+`Next.js` is moving to a `server-side`-first approach
+with their *`app router`*
+with [the introduction of `Server Components`](https://nextjs.org/docs/app/building-your-application/rendering/server-components).
+So this should be our approach.
+
+*However*, `Nextra` does [**not yet support `app router`**](https://github.com/shuding/nextra/issues/2023).
+This makes it so that the statically rendered pages are **client components**.
+If we take a look at [`auth.js`'s documentation](https://authjs.dev/getting-started/migrating-to-v5#authenticating-server-side),
+we quickly realise that we can't use the `auth()` call like we did in `src/middleware.ts`
+inside our theme's components.
+In fact, we can only use [`useSession()`](https://next-auth.js.org/getting-started/client#usesession)
+to fetch the current session of the logged in person.
+
+> [!NOTE]
+>
+> We *did try* using the `auth()` call,
+> but we were always prompted with the same error:
+> ```
+> unhandledRejection: Error: `headers` was called outside a request scope. Read more: https://nextjs.org/docs/messages/next-dynamic-api-wrong-context
+> ```
+> Reading the link in the error,
+> this happens because calling `headers()` is made within the library,
+> which *is out of the scope of the theme*, making it impossible to do it "server-side".
+>
+> Even after [updating the `handlers` inside `app/api/auth/[...nextauth]/route.ts`](https://github.com/vercel/next.js/issues/50679#issuecomment-1573705463)
+> and simply overriding the default theme through `theme.config.jsx`,
+> the same error occurred.
+
+While this may seem not like the ideal scenario,
+it's important to stress **that the routes are still protected**
+and that the issued [`JWT` are encrypted by default.](https://authjs.dev/reference/core/jwt).
+So, while very unlikely, the person may *know some links exist*,
+but they can't access it,
+as they are protected server-side through `middleware.ts`.
+
+
+### 7.2 Using `useSession()`
+
+Now that we know we're using the `useSession()` hook to retrieve the person's current session,
+let's make some changes to our code so we can use it!
+
+The first thing we need to do
+is to wrap our app with [``](https://next-auth.js.org/getting-started/client#sessionprovider).
+This will ensure the session is accessible throughout the application.
+
+Head over to `src/pages/_app.tsx`,
+and change it to the following.
+
+```ts
+// These styles apply to every route in the application
+import '@/src/globals.css'
+import type { AppProps } from 'next/app'
+import { SessionProvider } from "next-auth/react"
+
+export default function MyApp({
+ Component,
+ pageProps: { session, ...pageProps },
+}: AppProps) {
+ return (
+
+ ;
+
+ )
+}
+```
+
+Awesome!
+
+Before proceeding, let's do some housekeeping ๐งน.
+We *know* we are going to need two things:
+- use the extended `User` interface
+that we augmented inside `auth`.
+- use the `PrivateInfo` type inside `src/generatePrivateRoutes.ts`
+to know whether a menu item is private or not.
+
+Let's start with the first one.
+Inside `src/auth.ts`,
+locate the augmented `Session` interface.
+Change it to the following.
+
+```ts
+import { ExtendedUser } from './types'; // added this
+
+declare module "next-auth" {
+ interface Session extends DefaultSession {
+ user: ExtendedUser // changed here
+
+
+ }
+
+ interface User {
+ // Additional properties here:
+ role?: string;
+ }
+}
+```
+
+Notice that we've created an `ExtendedUser` interface
+that is imported from `types.ts`.
+We haven't created this file.
+So let's do it!
+Inside `src`, create a file called `types.ts`.
+
+```ts
+import { type DefaultSession } from 'next-auth';
+/**
+ * Holds types for the application (on the `src` side)
+ */
+
+// Types for the `_meta.json` structure
+export type PrivateInfo = {
+ private: boolean;
+ roles?: string[];
+};
+
+export type MetaJson = {
+ [key: string]: string | any | PrivateInfo;
+};
+
+export type PrivateRoutes = {
+ [key: string]: string[];
+};
+
+// Types for auth
+export type ExtendedUser = {
+ role?: string;
+ } & DefaultSession["user"];
+```
+
+Notice that we simply moved the extended user code
+to `ExtendedUser` inside this file.
+In addition to this, we have also copied the types
+from `src/generatePrivateRoutes.ts` to here, as well.
+All that is left to do is update `src/generatePrivateRoutes.ts`
+to import these!
+
+```ts
+// generatePrivateRoutes.ts
+import { PrivateRoutes, MetaJson } from './types';
+
+// delete the types
+// ...
+```
+
+And that's it!
+We're ready to rock and roll! ๐ธ
+
+
+### 7.3 Rendering links inside `navbar`
+
+Let's start by conditionally rendering the links
+inside the `navbar`.
+
+First let's go `theme/src/types.ts`
+and add two additional types for the
+`PageItem` and `MenuItem` types
+that are used inside `theme/src/components/navbar.tsx`.
+
+Add the following lines.
+
+```ts
+// `theme/src/types.ts`
+
+import type { MenuItem, PageItem } from 'nextra/normalize-pages'
+import { PrivateInfo } from '../../src/types';
+
+// Extends the PageItem and MenuItem with the `private` property
+export type ExtendedPageItem = { private?: PrivateInfo } & PageItem;
+export type ExtendedMenuItem = { private?: PrivateInfo } & MenuItem;
+```
+
+We are simply extending the `PageItem` and `MenuItem` types
+with the `PrivateInfo` interface that we moved earlier.
+This way, we'll have access to the `private` property when writing code
+inside `navbar.tsx`!
+
+Speaking of which,
+let's finally change the `navbar.tsx` component!
+Head over to `theme/src/components/navbar.tsx`
+
+First, locate the `NavBarProps` type
+on top of the file and change it accordingly.
+We are extending our items' types with the extended types we've defined before
+so we can access the `private` property.
+
+```ts
+export type NavBarProps = {
+ flatDirectories: Item[]
+ items: (ExtendedPageItem | ExtendedMenuItem)[]
+}
+```
+
+Now we're ready to make some changes to the `NavBar` function.
+Head over to this function and use the `useSession()` hook.
+
+```ts
+// theme/src/components/navbar.tsx
+
+import { useSession } from "next-auth/react"
+import { ExtendedPageItem, ExtendedMenuItem } from '../types';
+import { ExtendedUser } from '../../../src/types';
+
+export function Navbar({ flatDirectories, items }: NavBarProps): ReactElement {
+ const config = useConfig()
+ const activeRoute = useFSRoute()
+ const { menu, setMenu } = useMenu()
+
+ const {data, status: session_status} = useSession() // add this
+ const user = data?.user as ExtendedUser // add this
+
+ return (
+ ...
+ )
+```
+
+Great!
+We are now successfully using the `useSession()` hook
+and getting the authenticated (or not) person's session data.
+Now we can leverage this data
+to conditionally render the links inside our `NavBar`!
+
+Because the `Session` object returned by `useSession`
+also has a `status`
+[(that can be either `"loading"`, `"authenticated"` or `"unauthenticated"`)](https://next-auth.js.org/getting-started/client#usesession),
+we will have to take this into account when changing
+how the `NavBar` renders the links.
+
+Other than this,
+all we have to do is block the rendering
+of links that the user is **not allowed to see**.
+Locate the `return` of the `NavBar` function
+and implement the following changes.
+
+```ts
+ return (
+
+
+