Launching the Markdown Blog Template

Welcome to the official launch of the Markdown Blog Template! This project is a modern, robust, and fully local solution for creators who want:

• Full control over their content and structure
• No external dependencies (no APIs, no third-party CMS)
• Obsidian-style markdown features (callouts, wiki-links, checkboxes, GFM, etc.)
• Beautiful, modern UI/UX with category, post, and page support
• SEO best practices (sitemaps, robots.txt, dynamic meta tags)

What's New in 2025 Release

• Tag Cloud & Tag Pages: Auto-generate /tags overview and per-tag pages—no config needed.
• Client-Side Search: Pre-build a static search-index.json and search entirely in-browser—no API routes.
• Full Static Export: Use output: 'export' and generateStaticParams() to export all pages to pure HTML.
• Improved UX: Dark-mode default, no hydration mismatches, and responsive nav/search toggles.
• Enhanced SEO: JSON-LD structured data, canonical URLs, and dynamic metadata for better search rankings.
• Performance Optimizations: Image optimization, lazy loading, and route prefetching for lightning-fast page loads.
• Advanced Markdown: Support for callouts, task lists, and syntax highlighting with dark mode compatibility.

How It Works

• Content lives in your repo: All posts are markdown files in content/posts/. Static pages are in content/pages/.
• Categories: Defined in lib/categories.ts and used for filtering, navigation, and sitemaps.
• Slug logic: Uses frontmatter slug if present, else generates from filename.
• Cover images: Supports local images (in attachments/) or web URLs. If missing, a dark placeholder with the post/page title is shown.
• Wiki-links: Use [[Page Name]] or [[slug]] to link between posts and pages. Links resolve to published content only.
• Markdown rendering: Supports GFM, callouts, checkboxes, and more. Images are styled for aspect ratio and animation.
• Pagination: Home, blog, and category pages paginate posts (9 per page).
• SEO: Dynamic OpenGraph, Twitter, and meta tags. Sitemaps and robots.txt are auto-generated.

How It Works Under the Hood

• Tags: Parsed from frontmatter (tags: array or comma-separated string) and exposed via a tag cloud component. Tags automatically generate /tags overview and individual /tags/[slug] pages.
• Search: A build-time script generates public/search-index.json—your search bar filters this JSON client-side. The search API also supports server-side search across titles, excerpts, and content.
• Static Export: All dynamic routes ([slug], /blog, /category, /tags) use generateStaticParams to pre-render at build time.
• Category System: Categories support images, descriptions, and provide an organized way to browse content with pagination support.
• Custom Components: UI components like PostTagCloud, PaginatedTagGrid, and BlogSearch make for a rich user experience.

Project Structure

• Next.js App Router: Built with the Next.js App Router for optimal performance and SEO.
• Content Directory: All content is stored in content/ with subdirectories for posts/ and pages/.
• UI Components: Reusable UI components in app/components/ make customization easy.
• Utils & Config: Configuration in app/lib/ including config.ts, categories.ts, and tags.ts.
• Route Handlers: API routes in app/api/ handle dynamic features like search.
• Styles: Global styles in app/stylesheets/ with specific files for markdown, callouts, and code blocks.

Getting Started

1. Clone the Repo and Install Dependencies

git clone <your-repo-url>
cd markdown-blog
npm install

2. Add Your Content

• Blog posts: Place markdown files in content/posts/.
• Static pages: Place markdown files in content/pages/.
• Attachments: Place images or files in attachments/ and reference them in your markdown frontmatter or content.
• Tags: Add tags: in frontmatter (array or CSV). These appear as clickable chips in each post.

3. Build & Export Static Site

npm run export:static

This script will:

• Generate public/search-index.json for client-side search.
• Build your Next.js site.
• Export all pages to the out/ directory as static HTML.

4. Edit Site Configuration

• Update site name, tagline, logo, and other details in lib/config.ts under siteInfo.
• Example:

  export const siteConfig = {
    siteInfo: {
      name: 'Your Site Name',
      tagLine: 'Your Tagline',
      logo: '/images/favicon.avif',
      description: 'A modern markdown-powered blog.',
      siteUrl: 'https://yourdomain.com',
      ogImage: '/logo.svg',
      // ...
    },
    // ...
  }
  

5. Customize Categories

• Edit lib/categories.ts to add, remove, or update categories. Each category has a slug, name, description, and optional coverImage.
• Example:

  export const categories = [
    { slug: 'general', name: 'General', description: 'General posts', coverImage: '/images/general.jpg' },
    // ...
  ];
  

6. Run Locally

npm run dev

7. Deploy

Deploy to Vercel, Netlify, or your favorite platform. Make sure to set the NEXT_PUBLIC_SITE_URL environment variable for correct sitemap/SEO URLs.

Run:

npm run export:static

This builds the static search index, compiles the site, and exports out/ with 100% static HTML assets.

---

Adding a New Blog Post

1. Create a Markdown file in content/posts/ (e.g., my-first-post.md).
2. Add frontmatter at the top:

---
title: "My First Post"
slug: "my-first-post"
date: "2025-05-15"
category: "General"
published: true
coverImage: "/images/dark-placeholder.svg" # or a web URL or local attachment
excerpt: "A quick intro to the markdown blog template."
---

3. Write your content below the frontmatter using markdown. You can use:

   • Images: ![Alt text](url)
   • Wiki-links: [[Another Post]]
   • Callouts: > [!NOTE] This is a note.
   • Checkboxes, tables, GFM, etc.

4. SEO Details:

   • title: Used for the page <title> and OpenGraph/Twitter meta tags.
   • excerpt: Used for meta description and social sharing.
   • coverImage: Used for OpenGraph/Twitter images and as the post cover.
   • date: Used for <lastmod> in sitemaps and post meta.
   • slug: Used for the post URL (/blog/slug).
   • published: Only posts with published: true appear on the site and in sitemaps.

---

Adding a New Static Page

1. Create a Markdown file in content/pages/ (e.g., about.md).
2. Add frontmatter at the top:

---
title: "About"
slug: "about"
published: true
coverImage: "/images/dark-placeholder.svg" # or a web URL or local attachment
excerpt: "About this site."
---

3. Write your content below the frontmatter using markdown. All markdown features and wiki-links are supported.

4. SEO Details:

   • title: Used for the page <title> and OpenGraph/Twitter meta tags.
   • excerpt: Used for meta description and social sharing.
   • coverImage: Used for OpenGraph/Twitter images and as the page cover.
   • slug: Used for the page URL (/slug).
   • published: Only pages with published: true appear on the site and in sitemaps.

---

SEO & Social Sharing

• Meta tags: Titles, descriptions, and images are generated from frontmatter for each post/page.
• OpenGraph & Twitter: Social cards use the coverImage, title, and excerpt.
• Sitemaps: /sitemap.xml and sub-sitemaps are auto-generated for posts, pages, categories, and tags.
• robots.txt: Included and points to your sitemap.
• Noindex: Unpublished posts/pages are not indexed or included in sitemaps.
• JSON-LD: Structured data for rich search results with article, breadcrumbs, and organization schema.
• Canonical URLs: Properly implemented to avoid duplicate content issues.
• Metadata API: Next.js metadata API used to generate SEO tags dynamically.

---

Features

• Modern, responsive design
• Featured posts and sliders
• Category and post grids
• Static page support (/[slug])
• Robust image and cover handling
• Wiki-link navigation
• SEO and social sharing
• Pagination and filtering
• Tag cloud and tag pages
• Client-side search
• Dynamic metadata
• Mobile-optimized layout
• Dark mode with system detection

---

Documentation

• Add a post: Create a markdown file in content/posts/ with the required frontmatter.
• Add a static page: Create a markdown file in content/pages/.
• Add a category: Edit lib/categories.ts.
• Add a cover image: Use a web URL or place an image in attachments/ and reference it in frontmatter.
• Wiki-links: Use [[Page Name]] or [[slug]] in your markdown to link to other published posts/pages.
• Add tags: Include a tags array or comma-separated string in your frontmatter. Tags are automatically displayed and linked via the tag cloud.
• SEO: Edit frontmatter for title, excerpt, and coverImage. Sitemaps and robots.txt are auto-generated.
• Search: Client-side search is automatic - the search index is built at compile time from your content.

For more, see the README or explore the codebase!

Stay tuned for more features and contributions—happy blogging!