<div class="demo-layout">

  <!-- TOC Sidebar -->
  <nav class="toc" id="toc" aria-label="Table of contents">
    <div class="toc-head">On this page</div>
    <ul class="toc-list" id="toc-list"></ul>
  </nav>

  <!-- Article content -->
  <article class="article" id="article">
    <h1>Getting started with Next.js</h1>

    <h2 id="installation">Installation</h2>
    <p>Run npx create-next-app@latest to scaffold a new Next.js project. The CLI will ask you several questions about TypeScript, ESLint, Tailwind CSS, and the App Router. Choose the options that match your project requirements.</p>
    <p>Once the project is created, run npm run dev to start the development server on port 3000. The project comes pre-configured with hot module replacement, so changes you make to files are reflected in the browser instantly without a full page reload.</p>
    <p>Node.js 18.17 or later is required. You can check your version with node -v. If you need to manage multiple Node versions, nvm (Node Version Manager) makes switching between them straightforward.</p>

    <h2 id="project-structure">Project structure</h2>
    <p>Next.js 15 with the App Router organises your application inside the app directory. Each folder in app corresponds to a route segment. Special files like layout.js, page.js, and loading.js control the UI and behaviour of each route.</p>
    <p>The public folder holds static assets like images and fonts that are served directly from the root URL. Files placed here are accessible at the path /filename — no import required. Keep images optimised before placing them here since Next.js serves them as-is.</p>
    <p>Configuration lives in next.config.mjs at the root. This is where you enable features like image domains, redirects, environment variable exposure, and custom webpack settings. Most projects only need a handful of lines here.</p>

    <h3 id="app-directory">The app directory</h3>
    <p>The app directory enables React Server Components by default. Components defined here run on the server unless you add the "use client" directive. This model dramatically reduces JavaScript sent to the browser since server-only logic like database queries never ships to the client.</p>
    <p>Special files inside any route folder have reserved roles: layout.js wraps all child routes and persists across navigation; page.js is the publicly accessible UI; loading.js shows a skeleton while the page streams in; error.js catches runtime errors and renders a fallback.</p>

    <h3 id="pages-directory">The pages directory</h3>
    <p>The pages directory uses the older Pages Router. Both routers can coexist in the same application — useful when migrating an existing app incrementally to the App Router. Files placed inside pages automatically become routes, with index.js mapping to the root.</p>
    <p>API routes in the pages router live in pages/api and export handler functions. They run on the server and are useful for form submissions, webhook receivers, and lightweight backend logic without standing up a separate API server.</p>

    <h2 id="routing">Routing</h2>
    <p>File-based routing is one of Next.js's defining features. Every file in the app directory automatically becomes a route. Dynamic segments are created with square bracket syntax: [id] matches any value and provides it as a param to the component.</p>
    <p>Route groups created with (parentheses) let you organise folders without affecting the URL. Parallel routes defined with @slot allow multiple pages to render side by side in the same layout — useful for dashboards with independently loading panels.</p>
    <p>Linking between routes uses the Link component from next/link. It prefetches the linked page in the background when the link enters the viewport, making navigation feel instant. For programmatic navigation, useRouter from next/navigation provides push, replace, and back methods.</p>

    <h3 id="dynamic-routes">Dynamic routes</h3>
    <p>Dynamic routes like app/blog/[slug]/page.js match paths such as /blog/my-first-post. The slug is available via the params prop in the page component. Use generateStaticParams to pre-render dynamic routes at build time for optimal performance.</p>
    <p>Catch-all segments using [...slug] match any number of path segments. Optional catch-all segments [[...slug]] also match the route with no segments at all. These are useful for documentation sites where the depth of the URL hierarchy isn't known ahead of time.</p>

    <h2 id="data-fetching">Data fetching</h2>
    <p>Server Components can fetch data directly using async/await. This happens on the server during rendering. The result is streamed to the client. Use the React cache() function to deduplicate requests for the same data within a single render.</p>
    <p>Next.js extends the native fetch API with caching options. Pass cache: 'no-store' for always-fresh data, or next: &#123; revalidate: 60 &#125; to refresh cached data every 60 seconds. This incremental static regeneration approach gives you the performance of static with the freshness of dynamic.</p>
    <p>For client-side data fetching after the initial render, SWR and React Query both work well in Next.js Client Components. They handle caching, revalidation, and loading states so you don't have to manage useEffect-based fetching manually.</p>

    <h2 id="deployment">Deployment</h2>
    <p>Deploying a Next.js application to Vercel requires only connecting your Git repository. Vercel automatically detects Next.js and configures the build process. Every push to main triggers a production deployment; every pull request gets its own preview URL.</p>
    <p>For self-hosted deployments, run npm run build to produce an optimised production build, then npm start to serve it. You can also export a fully static site with output: 'export' in next.config.mjs — the result is plain HTML, CSS, and JS that can be served from any CDN or static host.</p>
    <p>Environment variables are loaded from .env.local in development and from your hosting provider's dashboard in production. Prefix variables with NEXT_PUBLIC_ to expose them to the browser; all others remain server-only and are never included in the client bundle.</p>
  </article>

</div>

* { box-sizing: border-box; margin: 0; padding: 0; }
body { font-family: system-ui, sans-serif; background: #f8fafc; min-height: 100vh; padding: 32px 20px; }

.demo-layout { max-width: 900px; margin: 0 auto; display: grid; grid-template-columns: 220px 1fr; gap: 48px; align-items: start; }
@media (max-width: 700px) { .demo-layout { grid-template-columns: 1fr; } .toc { display: none; } }

/* TOC */
.toc { position: sticky; top: 20px; padding: 16px; background: #fff; border-radius: 12px; border: 1px solid #e2e8f0; }
.toc-head { font-size: 11px; font-weight: 700; letter-spacing: 1px; text-transform: uppercase; color: #94a3b8; margin-bottom: 12px; }

.toc-list { list-style: none; display: flex; flex-direction: column; gap: 2px; }
.toc-item { }
.toc-link { display: block; font-size: 13px; color: #64748b; text-decoration: none; padding: 4px 8px; border-radius: 6px; border-left: 2px solid transparent; transition: color 0.12s, background 0.12s, border-color 0.12s; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
.toc-link:hover { color: #0f172a; background: #f8fafc; }
.toc-link.active { color: #6366f1; border-left-color: #6366f1; font-weight: 600; }
.toc-link.h3 { font-size: 12px; padding-left: 18px; }

/* Article */
.article { background: #fff; border-radius: 14px; padding: 32px; border: 1px solid #e2e8f0; line-height: 1.75; }
.article h1 { font-size: 24px; font-weight: 800; color: #0f172a; margin-bottom: 28px; }
.article h2 { font-size: 18px; font-weight: 700; color: #0f172a; margin-top: 32px; margin-bottom: 12px; padding-top: 16px; border-top: 1px solid #f1f5f9; }
.article h2:first-of-type { border-top: none; margin-top: 0; }
.article h3 { font-size: 15px; font-weight: 700; color: #374151; margin-top: 20px; margin-bottom: 8px; }
.article p  { font-size: 14px; color: #475569; margin-bottom: 14px; }

// Build TOC from headings in the article
const article = document.getElementById('article');
const tocList  = document.getElementById('toc-list');
const headings = [...article.querySelectorAll('h2, h3')];

headings.forEach(h => {
  if (!h.id) h.id = h.textContent.trim().toLowerCase().replace(/\s+/g,'-').replace(/[^a-z0-9-]/g,'');
  const li = document.createElement('li');
  li.className = 'toc-item';
  const a = document.createElement('a');
  a.className = 'toc-link' + (h.tagName === 'H3' ? ' h3' : '');
  a.href = '#' + h.id;
  a.textContent = h.textContent;
  a.addEventListener('click', e => {
    e.preventDefault();
    h.scrollIntoView({ behavior: 'smooth', block: 'start' });
  });
  li.appendChild(a);
  tocList.appendChild(li);
});

// Highlight active section on scroll — only one item active at a time
const visible = new Set();
const observer = new IntersectionObserver(entries => {
  entries.forEach(entry => {
    if (entry.isIntersecting) visible.add(entry.target);
    else visible.delete(entry.target);
  });
  // Pick the topmost visible heading (earliest in document order)
  const active = headings.find(h => visible.has(h));
  tocList.querySelectorAll('a').forEach(a => a.classList.remove('active'));
  if (active) {
    const link = tocList.querySelector('a[href="#' + active.id + '"]');
    if (link) link.classList.add('active');
  }
}, { rootMargin: '-10% 0% -70% 0%', threshold: 0 });

headings.forEach(h => observer.observe(h));