@bivabdas/sharq 1.0.3 → 1.0.4

package/lib/config.js

@@ -2,8 +2,18 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
+function normalizeRouteSegment(value, fallback) {
+  const normalized = String(value || fallback)
+    .trim()
+    .replace(/^\/+|\/+$/g, "");
+
+  return normalized || fallback;
+}
+
 export function createConfig(rootDir, overrides = {}) {
   const buildDirName = overrides.buildDirName || "sharq";
+  const docsRouteSegment = normalizeRouteSegment(overrides.docsRouteSegment, "doc");
+  const docsRoutePath = `/${docsRouteSegment}`;
 
   return {
     rootDir,
@@ -12,11 +22,15 @@ export function createConfig(rootDir, overrides = {}) {
     siteDescription:
       overrides.siteDescription || "A tiny publishing surface that renders posts from Markdown and serves static HTML.",
     buildDirName,
+    docsSourceSlug: overrides.docsSourceSlug || "",
+    docsRouteSegment,
+    docsRoutePath,
     contentDir: path.join(rootDir, "content"),
     stylesDir: path.join(rootDir, "styles"),
     templatesDir: path.join(rootDir, "templates"),
     publicDir: path.join(rootDir, "public"),
     blogOutputDir: path.join(rootDir, "public", "blog"),
+    docsPagePath: path.join(rootDir, "public", docsRouteSegment, "index.html"),
     sitemapPath: path.join(rootDir, "public", "sitemap.xml"),
     homePagePath: path.join(rootDir, "public", "index.html"),
     archivePagePath: path.join(rootDir, "public", "archive.html"),

package/lib/generator.js

@@ -21,6 +21,37 @@ function assertValidSlug(slug) {
   }
 }
 
+function splitPosts(config, posts) {
+  if (!config.docsSourceSlug) {
+    return { docsPage: null, regularPosts: posts };
+  }
+
+  const docsPage = posts.find((post) => post.slug === config.docsSourceSlug) || null;
+  const regularPosts = posts.filter((post) => post.slug !== config.docsSourceSlug);
+  return { docsPage, regularPosts };
+}
+
+async function writeDocsPage(config, docsPage) {
+  if (!docsPage) {
+    await fs.rm(config.docsPagePath, { force: true });
+    return null;
+  }
+
+  await fs.mkdir(path.dirname(config.docsPagePath), { recursive: true });
+  const html = await renderPostPage(config, docsPage);
+  await fs.writeFile(config.docsPagePath, html, "utf8");
+  console.log(`[sharq] generated ${config.docsRoutePath}`);
+  return { ...docsPage, outputPath: config.docsPagePath, html };
+}
+
+async function removeStaleDocsBlogPage(config) {
+  if (!config.docsSourceSlug) {
+    return;
+  }
+
+  await fs.rm(path.join(config.blogOutputDir, `${config.docsSourceSlug}.html`), { force: true });
+}
+
 export async function listContentSlugs(config) {
   await ensureDirectories(config);
   const entries = await fs.readdir(config.contentDir, { withFileTypes: true });
@@ -42,6 +73,14 @@ export async function generatePost(config, slug) {
   assertValidSlug(slug);
 
   const post = await readPostSource(config, slug);
+
+  if (config.docsSourceSlug && slug === config.docsSourceSlug) {
+    const docsPage = await writeDocsPage(config, post);
+    await removeStaleDocsBlogPage(config);
+    await refreshSiteArtifacts(config);
+    return docsPage;
+  }
+
   const html = await renderPostPage(config, post);
   const outputPath = path.join(config.blogOutputDir, `${slug}.html`);
 
@@ -54,15 +93,18 @@ export async function generatePost(config, slug) {
 
 export async function refreshSiteArtifacts(config) {
   const posts = await getAllPosts(config);
-  const indexHtml = await renderIndexPage(config, posts);
-  const archiveHtml = await renderArchivePage(config, posts);
+  const { docsPage, regularPosts } = splitPosts(config, posts);
+  const indexHtml = await renderIndexPage(config, regularPosts);
+  const archiveHtml = await renderArchivePage(config, regularPosts);
 
   await fs.writeFile(config.homePagePath, indexHtml, "utf8");
   await fs.writeFile(config.archivePagePath, archiveHtml, "utf8");
-  await generateSitemap(config, posts);
-  console.log(`[sharq] refreshed homepage and sitemap for ${posts.length} post${posts.length === 1 ? "" : "s"}`);
+  await writeDocsPage(config, docsPage);
+  await removeStaleDocsBlogPage(config);
+  await generateSitemap(config, regularPosts, docsPage);
+  console.log(`[sharq] refreshed homepage and sitemap for ${regularPosts.length} post${regularPosts.length === 1 ? "" : "s"}`);
 
-  return posts;
+  return { posts: regularPosts, docsPage };
 }
 
 async function copyDirectory(sourceDir, targetDir) {
@@ -86,7 +128,7 @@ async function copyStaticFiles(config, outputDir) {
     const entries = await fs.readdir(config.publicDir, { withFileTypes: true });
 
     for (const entry of entries) {
-      if (entry.name === "blog") {
+      if (["blog", config.docsRouteSegment].includes(entry.name)) {
         continue;
       }
 
@@ -115,6 +157,7 @@ function createOutputConfig(config, outputDir) {
     ...config,
     publicDir: outputDir,
     blogOutputDir: path.join(outputDir, "blog"),
+    docsPagePath: path.join(outputDir, config.docsRouteSegment, "index.html"),
     sitemapPath: path.join(outputDir, "sitemap.xml"),
     homePagePath: path.join(outputDir, "index.html"),
     archivePagePath: path.join(outputDir, "archive.html"),
@@ -135,28 +178,31 @@ export async function buildStaticSite(config, outputDir = config.buildDir) {
   await copyStaticFiles(config, outputDir);
 
   const posts = await getAllPosts(config);
+  const { docsPage, regularPosts } = splitPosts(outputConfig, posts);
   await Promise.all(
-    posts.map(async (post) => {
+    regularPosts.map(async (post) => {
       const postHtml = await renderPostPage(outputConfig, post);
       const outputPath = path.join(outputConfig.blogOutputDir, `${post.slug}.html`);
       await fs.writeFile(outputPath, postHtml, "utf8");
     })
   );
 
-  const indexHtml = await renderIndexPage(outputConfig, posts);
-  const archiveHtml = await renderArchivePage(outputConfig, posts);
+  const indexHtml = await renderIndexPage(outputConfig, regularPosts);
+  const archiveHtml = await renderArchivePage(outputConfig, regularPosts);
 
   await fs.writeFile(outputConfig.homePagePath, indexHtml, "utf8");
   await fs.writeFile(outputConfig.archivePagePath, archiveHtml, "utf8");
-  await generateSitemap(outputConfig, posts);
+  await writeDocsPage(outputConfig, docsPage);
+  await generateSitemap(outputConfig, regularPosts, docsPage);
 
-  console.log(`[sharq] built ${posts.length} post${posts.length === 1 ? "" : "s"} to ${outputDir}`);
-  return { outputDir, posts };
+  console.log(`[sharq] built ${regularPosts.length} post${regularPosts.length === 1 ? "" : "s"} to ${outputDir}`);
+  return { outputDir, posts: regularPosts, docsPage };
 }
 
 export async function ensurePostGenerated(config, slug) {
   assertValidSlug(slug);
-  const outputPath = path.join(config.blogOutputDir, `${slug}.html`);
+  const isDocsPage = config.docsSourceSlug && slug === config.docsSourceSlug;
+  const outputPath = isDocsPage ? config.docsPagePath : path.join(config.blogOutputDir, `${slug}.html`);
   const sourcePath = path.join(config.contentDir, `${slug}.md`);
 
   try {

package/lib/renderer.js

@@ -228,7 +228,8 @@ export async function renderPostPage(config, post) {
     .join("");
 
   return applyTemplate(template, {
-    title: escapeHtml(`${post.title} | ${config.siteTitle}`),
+    pageTitle: escapeHtml(`${post.title} | ${config.siteTitle}`),
+    title: escapeHtml(post.title),
     description: escapeHtml(post.description),
     date: escapeHtml(post.date),
     author: escapeHtml(post.author || "sharq"),

package/lib/server.js

@@ -95,6 +95,13 @@ function createApp(config) {
         return;
       }
 
+      if (pathname === config.docsRoutePath || pathname === `${config.docsRoutePath}/`) {
+        await refreshSiteArtifacts(config);
+        await sendFile(response, config.docsPagePath);
+        logRequest(request.method || "GET", pathname, 200);
+        return;
+      }
+
       if (pathname.startsWith("/blog/")) {
         const slug = pathname.replace("/blog/", "").replace(/\/+$/, "");
 
@@ -103,6 +110,12 @@ function createApp(config) {
           return;
         }
 
+        if (config.docsSourceSlug && slug === config.docsSourceSlug) {
+          notFound(response, "Requested content does not exist.");
+          logRequest(request.method || "GET", pathname, 404);
+          return;
+        }
+
         const filePath = await ensurePostGenerated(config, slug);
         await sendFile(response, filePath);
         logRequest(request.method || "GET", pathname, 200);

package/lib/sitemap.js

@@ -4,10 +4,11 @@ function buildUrl(config, pathname) {
   return `${config.siteUrl}${pathname}`;
 }
 
-export async function generateSitemap(config, posts) {
+export async function generateSitemap(config, posts, docsPage = null) {
   const urls = [
     buildUrl(config, "/"),
     buildUrl(config, "/archive"),
+    ...(docsPage ? [buildUrl(config, config.docsRoutePath)] : []),
     ...posts.map((post) => buildUrl(config, `/blog/${post.slug}`))
   ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivabdas/sharq",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "A tiny static publishing framework for landing pages and markdown-driven sites.",
   "type": "module",
   "main": "index.js",

package/scaffold/template/templates/post.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>{{title}}</title>
+    <title>{{pageTitle}}</title>
     <meta name="description" content="{{description}}">
     <link rel="stylesheet" href="/assets/site.css">
     <link rel="stylesheet" href="/assets/overrides.css">