@raystack/chronicle 0.6.1 → 0.7.1

package/src/themes/paper/Layout.module.css

@@ -1,5 +1,17 @@
+@import url("https://fonts.googleapis.com/css2?family=Hanuman:wght@400;700&display=swap");
+
+@font-face {
+  font-family: "Departure Mono";
+  src: url("./fonts/DepartureMono-Regular.woff2") format("woff2");
+  font-weight: 400;
+  font-style: normal;
+  font-display: swap;
+}
+
 .layout {
-  --paper-sidebar-width: 260px;
+  --paper-sidebar-width: 262px;
+  --paper-font-mono: "Departure Mono", "SF Mono", "Fira Code", monospace;
+  --paper-font-body: "Hanuman", sans-serif;
 
   min-height: 100vh;
 }
@@ -8,33 +20,66 @@
   flex: 1;
 }
 
+:global(body) {
+  background: var(--rs-color-background-neutral-primary);
+}
+
 .sidebar {
   width: var(--paper-sidebar-width);
-  padding: var(--rs-space-7) var(--rs-space-5);
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  position: sticky;
+  top: 0;
   background: var(--rs-color-background-neutral-primary);
-  overflow-y: auto;
-  font-family: "SF Mono", "Fira Code", "Fira Mono", "Roboto Mono", monospace;
 }
 
-.title {
+.header {
+  display: flex;
+  align-items: center;
+  height: 48px;
+  padding: 0 var(--rs-space-5);
+  flex-shrink: 0;
+}
+
+.contentDirTrigger {
+  border: none;
+  outline: none;
+  background: var(--rs-color-background-neutral-primary);
+  color: var(--rs-color-foreground-accent-primary);
+  font-family: var(--paper-font-mono);
+  font-size: var(--rs-font-size-regular);
+  font-weight: var(--rs-font-weight-medium);
+  line-height: var(--rs-line-height-mini);
+  letter-spacing: var(--rs-letter-spacing-mini);
   text-transform: uppercase;
-  letter-spacing: 0.08em;
+}
+
+.title {
+  font-size: var(--rs-font-size-regular);
+  letter-spacing: var(--rs-letter-spacing-mini);
   color: var(--rs-color-foreground-accent-primary);
-  font-family: inherit;
-  font-size: var(--rs-font-size-mono-large);
-  margin-bottom: var(--rs-space-7);
+  font-family: var(--paper-font-mono);
+  text-transform: uppercase;
 }
 
-.nav {
-  display: flex;
-  flex-direction: column;
-  gap: var(--rs-space-3);
-  margin-bottom: var(--rs-space-7);
+.navScroll {
+  flex: 1;
+  overflow-y: auto;
+  padding: var(--rs-space-5) var(--rs-space-5);
+}
+
+.footer {
+  flex-shrink: 0;
+  padding: var(--rs-space-4) var(--rs-space-5);
+  border-top: 1px solid var(--rs-color-border-base-primary);
 }
 
 .content {
   flex: 1;
-  overflow-y: auto;
   background: var(--rs-color-background-neutral-primary);
-  padding-right: var(--paper-sidebar-width);
+}
+
+.hiddenTrigger {
+  display: none;
 }

package/src/themes/paper/Layout.tsx

@@ -1,44 +1,100 @@
 'use client';
 
-import { Flex, Headline } from '@raystack/apsara';
+import { Flex, Select, Text } from '@raystack/apsara';
 import { cx } from 'class-variance-authority';
+import { useLocation, useNavigate } from 'react-router';
+import { getLandingEntries } from '@/lib/config';
+import { getActiveContentDir } from '@/lib/navigation';
+import { usePageContext } from '@/lib/page-context';
+import { Search } from '@/components/ui/search';
 import type { ThemeLayoutProps } from '@/types';
 import { ChapterNav } from './ChapterNav';
-import { ContentDirDropdown } from './ContentDirDropdown';
 import styles from './Layout.module.css';
+import { ReaderModeProvider, useReaderMode } from './ReaderModeContext';
 import { VersionSwitcher } from './VersionSwitcher';
 
-export function Layout({
+function SidebarHeader({ config }: { config: ThemeLayoutProps['config'] }) {
+  const { version } = usePageContext();
+  const { pathname } = useLocation();
+  const navigate = useNavigate();
+
+  const entries = getLandingEntries(config, version.dir);
+
+  if (entries.length <= 1) {
+    return (
+      <Text size={2} weight={500} className={styles.title}>
+        {config.site.title}
+      </Text>
+    );
+  }
+
+  const activeDir = getActiveContentDir(pathname, config);
+  const activeEntry =
+    entries.find(e => e.contentDir === activeDir) ?? entries[0];
+
+  return (
+    <Select
+      value={activeEntry.contentDir}
+      onValueChange={(val: string) => {
+        const entry = entries.find(e => e.contentDir === val);
+        if (entry) navigate(entry.href);
+      }}
+    >
+      <Select.Trigger size='small' className={styles.contentDirTrigger}>
+        <Select.Value placeholder={activeEntry.label} className={styles.title} />
+      </Select.Trigger>
+      <Select.Content>
+        {entries.map(entry => (
+          <Select.Item key={entry.href} value={entry.contentDir}>
+            {entry.label}
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select>
+  );
+}
+
+function LayoutInner({
   children,
   config,
   tree,
   hideSidebar,
   classNames
 }: ThemeLayoutProps) {
+  const { readerMode } = useReaderMode();
+  const showSidebar = !hideSidebar && !readerMode;
+
   return (
     <Flex direction='column' className={cx(styles.layout, classNames?.layout)}>
       <Flex className={cx(styles.body, classNames?.body)}>
-        {hideSidebar ? null : (
+        {showSidebar ? (
           <aside className={cx(styles.sidebar, classNames?.sidebar)}>
-            <Headline
-              size='small'
-              weight='medium'
-              as='h1'
-              className={styles.title}
-            >
-              {config.site.title}
-            </Headline>
-            <div className={styles.nav}>
-              <VersionSwitcher />
-              <ContentDirDropdown />
+            <div className={styles.header}>
+              <SidebarHeader config={config} />
             </div>
-            <ChapterNav tree={tree} />
+            <div className={styles.navScroll}>
+              <ChapterNav tree={tree} />
+            </div>
+            {config.versions?.length ? (
+              <div className={styles.footer}>
+                <VersionSwitcher />
+              </div>
+            ) : null}
           </aside>
-        )}
+        ) : null}
         <div className={cx(styles.content, classNames?.content)}>
+          {config.search?.enabled && <Search classNames={{ trigger: styles.hiddenTrigger }} />}
           {children}
         </div>
       </Flex>
     </Flex>
   );
 }
+
+export function Layout(props: ThemeLayoutProps) {
+  return (
+    <ReaderModeProvider>
+      <LayoutInner {...props} />
+    </ReaderModeProvider>
+  );
+}

package/src/themes/paper/Page.module.css

@@ -1,76 +1,89 @@
 .main {
-  --paper-navbar-height: 40px;
-  --paper-navbar-padding: var(--rs-space-3);
-  --paper-navbar-total: calc(
-    var(--paper-navbar-height) +
-    var(--paper-navbar-padding) *
-    2 +
-    1px
-  );
-
   flex: 1;
-  max-width: 1024px;
+  width: 90%;
+  max-width: calc(1024px + var(--rs-space-17));
+  margin: 0 auto;
+  padding-top: var(--rs-space-12);
+  padding-right: var(--rs-space-17);
+}
+
+.readerMode {
+  padding-right: 0;
   margin: 0 auto;
 }
 
 .navbar {
-  height: var(--paper-navbar-height);
-  padding: var(--paper-navbar-padding) 0;
-  border-bottom: 1px solid var(--rs-color-border-base-primary);
+  display: flex;
+  align-items: center;
   justify-content: space-between;
-  width: 100%;
-  position: fixed;
-  top: 0;
+  height: 48px;
+  padding: var(--rs-space-2) var(--rs-space-7);
   background: var(--rs-color-background-neutral-primary);
+  backdrop-filter: blur(8px);
+  border-bottom: 0.5px solid var(--rs-color-border-base-primary);
+  position: sticky;
+  top: 0;
   z-index: 10;
-  max-width: 1024px;
 }
 
 .navLeft {
+  display: flex;
   align-items: center;
+  gap: var(--rs-space-3);
 }
 
 .navRight {
+  display: flex;
   align-items: center;
+  gap: var(--rs-space-3);
 }
 
-.arrow {
+.arrows {
   display: flex;
   align-items: center;
-  color: var(--rs-color-foreground-base-primary);
+  gap: var(--rs-space-2);
+}
+
+.arrowLink {
+  display: flex;
+  align-items: center;
+  justify-content: center;
   text-decoration: none;
+  color: var(--rs-color-foreground-base-primary);
+  padding: var(--rs-space-1);
+  border-radius: var(--rs-radius-2);
 }
 
-.arrow:hover {
+.arrowLink:hover {
   color: var(--rs-color-foreground-accent-primary);
 }
 
 .arrowDisabled {
   display: flex;
   align-items: center;
+  justify-content: center;
   color: var(--rs-color-foreground-base-tertiary);
   opacity: 0.4;
-  cursor: default;
-  border: none;
-  background: none;
-  padding: 0;
+  padding: var(--rs-space-1);
 }
 
 .breadcrumb {
-  font-family: "SF Mono", "Fira Code", monospace;
+  display: flex;
+  align-items: center;
+  font-family: var(--paper-font-mono);
   font-size: var(--rs-font-size-small);
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
-  margin-left: var(--rs-space-3);
+  line-height: var(--rs-line-height-small);
+  letter-spacing: var(--rs-letter-spacing-small);
 }
 
 .separator {
-  margin: 0 var(--rs-space-2);
+  margin: 0 var(--rs-space-1);
   color: var(--rs-color-foreground-base-tertiary);
 }
 
 .crumbLink {
   color: var(--rs-color-foreground-base-tertiary);
+  font-weight: var(--rs-font-weight-medium);
   text-decoration: none;
 }
 
@@ -80,29 +93,67 @@
 
 .crumbActive {
   color: var(--rs-color-foreground-base-primary);
-  font-weight: 600;
+  font-weight: var(--rs-font-weight-medium);
 }
 
 .article {
   flex: 1;
   min-width: 0;
-  margin-top: var(--paper-navbar-total);
+  width: 100%;
   padding: 0 var(--rs-space-7);
 }
 
-.searchButton {
-  height: 28px;
-  padding: 0 var(--rs-space-3);
+.articleHeader {
+  text-align: center;
+  max-width: 656px;
+  margin: 0 auto;
+}
+
+.readingTime {
+  display: block;
+  font-family: var(--paper-font-mono);
   font-size: var(--rs-font-size-small);
+  font-weight: var(--rs-font-weight-regular);
+  line-height: 1.67;
+  letter-spacing: var(--rs-letter-spacing-t1);
+  color: var(--rs-color-foreground-base-tertiary);
+  margin-bottom: var(--rs-space-5);
+}
+
+.articleTitle {
+  font-family: var(--paper-font-body);
+  font-size: var(--rs-space-8);
+  font-weight: var(--rs-font-weight-medium);
+  line-height: var(--rs-space-10);
+  letter-spacing: var(--rs-letter-spacing-t1);
+  text-align: center;
+  color: var(--rs-color-foreground-base-primary);
+  margin: 0;
+}
+
+.articleSeparator {
+  width: 55px;
   border: none;
-  box-shadow: none;
+  border-top: 1px solid var(--rs-color-border-base-primary);
+  margin: var(--rs-space-10) auto;
+}
+
+.articleDescription {
+  font-family: var(--paper-font-body);
+  font-size: var(--rs-space-4);
+  font-weight: var(--rs-font-weight-medium);
+  line-height: var(--rs-space-7);
+  letter-spacing: var(--rs-letter-spacing-t1);
+  text-align: center;
+  color: var(--rs-color-foreground-base-secondary);
+  margin: var(--rs-space-4) 0 0;
 }
 
 .content {
-  font-family: Georgia, "Times New Roman", serif;
+  font-family: var(--paper-font-body);
   line-height: 1.8;
   background: var(--rs-color-background-base-primary);
-  padding: var(--rs-space-9);
+  padding: var(--rs-space-15) var(--rs-space-9) var(--rs-space-9);
   border-left: 1px solid var(--rs-color-border-base-primary);
   border-right: 1px solid var(--rs-color-border-base-primary);
   box-shadow:
@@ -152,6 +203,7 @@
 
 .content p {
   margin: 0.75rem 0;
+  line-height: 2;
 }
 
 .content ul,

package/src/themes/paper/Page.tsx

@@ -1,16 +1,31 @@
-import { ChevronLeftIcon, ChevronRightIcon } from '@heroicons/react/24/outline';
-import { Flex } from '@raystack/apsara';
-import { useMemo } from 'react';
+import {
+  ArrowLeftIcon,
+  ArrowRightIcon,
+  ChevronRightIcon,
+  AdjustmentsHorizontalIcon,
+  EyeIcon,
+  SunIcon,
+  MoonIcon,
+  XMarkIcon,
+} from '@heroicons/react/24/outline';
+import { IconButton, useTheme } from '@raystack/apsara';
+import { useEffect, useMemo, useState } from 'react';
 import { Link as RouterLink, useLocation } from 'react-router';
 import { getBreadcrumbItems } from 'fumadocs-core/breadcrumb';
 import { flattenTree } from 'fumadocs-core/page-tree';
-import { Search } from '@/components/ui/search';
 import type { ThemePageProps } from '@/types';
 import styles from './Page.module.css';
+import { useReaderMode } from './ReaderModeContext';
 import { ReadingProgress } from './ReadingProgress';
 
-export function Page({ page, config, tree }: ThemePageProps) {
+export function Page({ page, tree }: ThemePageProps) {
   const { pathname } = useLocation();
+  const [settingsOpen, setSettingsOpen] = useState(false);
+  const [isClient, setIsClient] = useState(false);
+  const { resolvedTheme, setTheme } = useTheme();
+  const { readerMode, toggleReaderMode } = useReaderMode();
+
+  useEffect(() => { setIsClient(true); }, []);
 
   const { prev, next, crumbs } = useMemo(() => {
     const pages = flattenTree(tree.children);
@@ -32,47 +47,33 @@ export function Page({ page, config, tree }: ThemePageProps) {
 
   return (
     <>
-      <main className={styles.main}>
-        <Flex align='center' className={styles.navbar}>
-          <Flex align='center' gap='small' className={styles.navLeft}>
-            {prev ? (
-              <RouterLink
-                to={prev.url}
-                className={styles.arrow}
-                aria-label='Previous page'
-              >
-                <ChevronLeftIcon width={14} height={14} />
-              </RouterLink>
-            ) : (
-              <button
-                disabled
-                className={styles.arrowDisabled}
-                aria-label='Previous page'
-              >
-                <ChevronLeftIcon width={14} height={14} />
-              </button>
-            )}
-            {next ? (
-              <RouterLink
-                to={next.url}
-                className={styles.arrow}
-                aria-label='Next page'
-              >
-                <ChevronRightIcon width={14} height={14} />
-              </RouterLink>
-            ) : (
-              <button
-                disabled
-                className={styles.arrowDisabled}
-                aria-label='Next page'
-              >
-                <ChevronRightIcon width={14} height={14} />
-              </button>
-            )}
+      <main className={`${styles.main} ${readerMode ? styles.readerMode : ''}`}>
+        <div className={styles.navbar}>
+          <div className={styles.navLeft}>
+            <div className={styles.arrows}>
+              {prev ? (
+                <RouterLink to={prev.url} className={styles.arrowLink} aria-label='Previous page'>
+                  <ArrowLeftIcon width={14} height={14} />
+                </RouterLink>
+              ) : (
+                <span className={styles.arrowDisabled} aria-hidden='true'>
+                  <ArrowLeftIcon width={14} height={14} />
+                </span>
+              )}
+              {next ? (
+                <RouterLink to={next.url} className={styles.arrowLink} aria-label='Next page'>
+                  <ArrowRightIcon width={14} height={14} />
+                </RouterLink>
+              ) : (
+                <span className={styles.arrowDisabled} aria-hidden='true'>
+                  <ArrowRightIcon width={14} height={14} />
+                </span>
+              )}
+            </div>
             <nav className={styles.breadcrumb}>
               {crumbs.map((crumb, i) => (
                 <span key={crumb.href}>
-                  {i > 0 && <span className={styles.separator}>/</span>}
+                  {i > 0 && <ChevronRightIcon width={12} height={12} className={styles.separator} />}
                   {i === crumbs.length - 1 ? (
                     <span className={styles.crumbActive}>{crumb.label}</span>
                   ) : (
@@ -83,18 +84,53 @@ export function Page({ page, config, tree }: ThemePageProps) {
                 </span>
               ))}
             </nav>
-          </Flex>
-          <Flex align='center' className={styles.navRight}>
-            {config.search?.enabled && (
-              <Search className={styles.searchButton} />
+          </div>
+          <div className={styles.navRight}>
+            {settingsOpen ? (
+              <>
+                <IconButton size={2} onClick={toggleReaderMode} aria-label='Toggle reader mode'>
+                  <EyeIcon width={14} height={14} />
+                </IconButton>
+                {isClient && (
+                  <IconButton
+                    size={2}
+                    onClick={() => setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')}
+                    aria-label={resolvedTheme === 'dark' ? 'Switch to light theme' : 'Switch to dark theme'}
+                  >
+                    {resolvedTheme === 'dark'
+                      ? <SunIcon width={14} height={14} />
+                      : <MoonIcon width={14} height={14} />
+                    }
+                  </IconButton>
+                )}
+                <IconButton size={2} onClick={() => setSettingsOpen(false)} aria-label='Close settings'>
+                  <XMarkIcon width={14} height={14} />
+                </IconButton>
+              </>
+            ) : (
+              <IconButton size={2} onClick={() => setSettingsOpen(true)} aria-label='Open settings'>
+                <AdjustmentsHorizontalIcon width={14} height={14} />
+              </IconButton>
+            )}
+          </div>
+        </div>
+        <div className={styles.content}>
+          <header className={styles.articleHeader}>
+            {page.frontmatter._readingTime && (
+              <span className={styles.readingTime}>{page.frontmatter._readingTime}min Read</span>
+            )}
+            <h1 className={styles.articleTitle}>{page.frontmatter.title}</h1>
+            {page.frontmatter.description && (
+              <p className={styles.articleDescription}>{page.frontmatter.description}</p>
             )}
-          </Flex>
-        </Flex>
-        <article className={styles.article} data-article-content>
-          <div className={styles.content}>{page.content}</div>
-        </article>
+            <hr className={styles.articleSeparator} />
+          </header>
+          <article className={styles.article} data-article-content>
+            {page.content}
+          </article>
+        </div>
       </main>
-      <ReadingProgress items={page.toc} />
+      {!readerMode && <ReadingProgress items={page.toc} />}
     </>
   );
 }

package/src/themes/paper/ReaderModeContext.tsx

@@ -0,0 +1,28 @@
+'use client';
+
+import { createContext, useContext, useState, type ReactNode } from 'react';
+
+interface ReaderModeContextValue {
+  readerMode: boolean;
+  toggleReaderMode: () => void;
+}
+
+const ReaderModeContext = createContext<ReaderModeContextValue>({
+  readerMode: false,
+  toggleReaderMode: () => {},
+});
+
+export function ReaderModeProvider({ children }: { children: ReactNode }) {
+  const [readerMode, setReaderMode] = useState(false);
+  return (
+    <ReaderModeContext.Provider
+      value={{ readerMode, toggleReaderMode: () => setReaderMode(v => !v) }}
+    >
+      {children}
+    </ReaderModeContext.Provider>
+  );
+}
+
+export function useReaderMode() {
+  return useContext(ReaderModeContext);
+}

package/src/themes/paper/ReadingProgress.tsx

@@ -220,6 +220,7 @@ export function ReadingProgress({ items }: ReadingProgressProps) {
     const element = document.getElementById(id);
     if (!element) return;
 
+    history.pushState(null, '', `#${id}`);
     const elementTop = element.getBoundingClientRect().top + window.scrollY;
     window.scrollTo({
       top: Math.max(0, elementTop - NAV_HEIGHT),

package/src/themes/registry.ts

@@ -15,7 +15,7 @@ export function getTheme(name?: string): Theme {
 
 export function getThemeConfig(name?: string) {
   if (name === 'paper') {
-    return { enableSystem: false, forcedTheme: 'light' };
+    return { enableSystem: true };
   }
   return { enableSystem: true };
 }

package/src/types/config.ts

@@ -84,6 +84,7 @@ const dirNameSchema = z
 const contentEntrySchema = z.object({
   dir: dirNameSchema,
   label: z.string().min(1),
+  description: z.string().optional(),
   icon: z.string().optional(),
 })
 

package/src/types/content.ts

@@ -10,6 +10,7 @@ export interface Frontmatter {
   order?: number
   icon?: string
   lastModified?: string
+  _readingTime?: number
 }
 
 export interface PageNavLink {

package/src/lib/remark-strip-md-extensions.ts

@@ -1,14 +0,0 @@
-import { visit } from 'unist-util-visit'
-import type { Plugin } from 'unified'
-
-const remarkStripMdExtensions: Plugin = () => {
-  return (tree) => {
-    visit(tree, 'link', (node: any) => {
-      if (!node.url) return
-      if (node.url.startsWith('http://') || node.url.startsWith('https://')) return
-      node.url = node.url.replace(/\.mdx?(#|$)/, '$1')
-    })
-  }
-}
-
-export default remarkStripMdExtensions