@bivabdas/sharq 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

package/README.md

@@ -0,0 +1,83 @@
+# sharq
+
+`sharq` is a minimal static rendering framework for landing pages and Markdown-driven blogs. It generates crawl-friendly HTML, keeps output on disk, and can scaffold a new site with a single command.
+
+## Features
+
+- Markdown posts with frontmatter
+- Static HTML output in `public/`
+- On-demand post generation
+- Index, archive, and sitemap generation
+- Zero-dependency runtime on native Node.js APIs
+
+## Install
+
+```bash
+npm install sharq
+```
+
+## CLI
+
+```bash
+sharq start
+sharq dev
+sharq build
+sharq create my-site
+create-sharq my-site
+```
+
+`sharq build` creates a fresh `sharq/` folder with deployable static files:
+
+```text
+sharq/
+  index.html
+  archive.html
+  sitemap.xml
+  assets/
+  blog/
+```
+
+## Content format
+
+Posts live in `content/*.md` and use frontmatter:
+
+```md
+---
+title: Hello sharq
+description: Your first sharq post.
+date: 2026-04-04
+author: You
+tags: welcome, getting-started
+---
+
+# Hello sharq
+
+This site was scaffolded with sharq.
+```
+
+## Project structure
+
+```text
+content/
+templates/
+public/
+sharq.config.js
+```
+
+## Configuration
+
+```js
+export default {
+  siteTitle: "My Site",
+  siteDescription: "A sharq site",
+  siteUrl: "https://example.com"
+};
+```
+
+## Publish checklist
+
+- Set `siteUrl` in `sharq.config.js`
+- Add your content in `content/`
+- Customize templates in `templates/`
+- Run `npm run build`
+- Ship the generated `sharq/` output with your hosting flow

package/bin/create-sharq.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readPackageVersion } from "../lib/package-info.js";
+import { scaffoldProject } from "../lib/scaffold.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+const projectName = process.argv[2];
+const packageVersion = await readPackageVersion(packageRoot);
+
+if (projectName === "--help" || projectName === "-h" || projectName === "help") {
+  console.log(`create-sharq v${packageVersion}
+
+Usage:
+  create-sharq [project-name]
+`);
+  process.exit(0);
+}
+
+const project = await scaffoldProject({
+  packageRoot,
+  frameworkVersion: `^${packageVersion}`,
+  projectName
+});
+
+console.log(`\nCreated ${project.projectName} at ${project.projectDir}`);
+console.log("\nNext steps:");
+console.log(`  cd ${project.projectName}`);
+console.log("  npm install");
+console.log("  npm run dev");

package/bin/sharq.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveConfig } from "../lib/config.js";
+import { buildStaticSite } from "../lib/generator.js";
+import { readPackageVersion } from "../lib/package-info.js";
+import { startServer } from "../lib/server.js";
+import { scaffoldProject } from "../lib/scaffold.js";
+
+const [, , command, projectName] = process.argv;
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+const packageVersion = await readPackageVersion(packageRoot);
+
+function printHelp() {
+  console.log(`sharq v${packageVersion}
+
+Usage:
+  sharq
+  sharq start
+  sharq dev
+  sharq build
+  sharq create [project-name]
+
+Commands:
+  start   Start the local sharq server
+  dev     Alias for start, intended for local development
+  build   Generate a deployable static site in ./sharq
+  create  Scaffold a new sharq site
+`);
+}
+
+if (!command || command === "dev" || command === "start") {
+  await startServer();
+} else if (command === "build") {
+  const config = await resolveConfig();
+  await buildStaticSite(config);
+} else if (command === "--help" || command === "-h" || command === "help") {
+  printHelp();
+} else if (command === "create") {
+  const project = await scaffoldProject({
+    packageRoot,
+    frameworkVersion: `^${packageVersion}`,
+    projectName
+  });
+
+  console.log(`\nCreated ${project.projectName} at ${project.projectDir}`);
+  console.log("\nNext steps:");
+  console.log(`  cd ${project.projectName}`);
+  console.log("  npm install");
+  console.log("  npm run dev");
+} else {
+  console.error(`Unknown sharq command: ${command}`);
+  process.exit(1);
+}

package/index.js

@@ -0,0 +1,4 @@
+export { resolveConfig, createConfig } from "./lib/config.js";
+export { buildStaticSite, generatePost, refreshSiteArtifacts, getAllPosts, ensurePostGenerated } from "./lib/generator.js";
+export { startServer } from "./lib/server.js";
+export { scaffoldProject } from "./lib/scaffold.js";

package/lib/config.js

@@ -0,0 +1,51 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export function createConfig(rootDir, overrides = {}) {
+  const buildDirName = overrides.buildDirName || "sharq";
+
+  return {
+    rootDir,
+    siteUrl: overrides.siteUrl || process.env.SITE_URL || "http://localhost:3000",
+    siteTitle: overrides.siteTitle || "sharq",
+    siteDescription:
+      overrides.siteDescription || "A tiny publishing surface that renders posts from Markdown and serves static HTML.",
+    buildDirName,
+    contentDir: path.join(rootDir, "content"),
+    templatesDir: path.join(rootDir, "templates"),
+    publicDir: path.join(rootDir, "public"),
+    blogOutputDir: path.join(rootDir, "public", "blog"),
+    sitemapPath: path.join(rootDir, "public", "sitemap.xml"),
+    homePagePath: path.join(rootDir, "public", "index.html"),
+    archivePagePath: path.join(rootDir, "public", "archive.html"),
+    staticAssetsDir: path.join(rootDir, "public", "assets"),
+    buildDir: path.join(rootDir, buildDirName)
+  };
+}
+
+export async function loadUserConfig(rootDir) {
+  const configPaths = [path.join(rootDir, "sharq.config.js"), path.join(rootDir, "statiq.config.js")];
+
+  for (const configPath of configPaths) {
+    try {
+      await fs.access(configPath);
+      const module = await import(`${pathToFileURL(configPath).href}?t=${Date.now()}`);
+      const loaded = module.default ?? module.config ?? {};
+      return typeof loaded === "function" ? loaded() : loaded;
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        continue;
+      }
+
+      throw error;
+    }
+  }
+
+  return {};
+}
+
+export async function resolveConfig(rootDir = process.cwd()) {
+  const userConfig = await loadUserConfig(rootDir);
+  return createConfig(rootDir, userConfig);
+}

package/lib/generator.js

@@ -0,0 +1,172 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { generateSitemap } from "./sitemap.js";
+import { readPostSource, renderArchivePage, renderIndexPage, renderPostPage } from "./renderer.js";
+
+async function ensureDirectories(config) {
+  await Promise.all([
+    fs.mkdir(config.contentDir, { recursive: true }),
+    fs.mkdir(config.publicDir, { recursive: true }),
+    fs.mkdir(config.blogOutputDir, { recursive: true }),
+    fs.mkdir(config.templatesDir, { recursive: true }),
+    fs.mkdir(config.staticAssetsDir, { recursive: true })
+  ]);
+}
+
+function assertValidSlug(slug) {
+  if (!/^[a-z0-9-]+$/i.test(slug)) {
+    throw new Error("Invalid slug format.");
+  }
+}
+
+export async function listContentSlugs(config) {
+  await ensureDirectories(config);
+  const entries = await fs.readdir(config.contentDir, { withFileTypes: true });
+
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .map((entry) => entry.name.replace(/\.md$/, ""));
+}
+
+export async function getAllPosts(config) {
+  const slugs = await listContentSlugs(config);
+  const posts = await Promise.all(slugs.map((slug) => readPostSource(config, slug)));
+
+  return posts.sort((left, right) => right.date.localeCompare(left.date));
+}
+
+export async function generatePost(config, slug) {
+  await ensureDirectories(config);
+  assertValidSlug(slug);
+
+  const post = await readPostSource(config, slug);
+  const html = await renderPostPage(config, post);
+  const outputPath = path.join(config.blogOutputDir, `${slug}.html`);
+
+  await fs.writeFile(outputPath, html, "utf8");
+  console.log(`[sharq] generated /blog/${slug}`);
+  await refreshSiteArtifacts(config);
+
+  return { ...post, outputPath, html };
+}
+
+export async function refreshSiteArtifacts(config) {
+  const posts = await getAllPosts(config);
+  const indexHtml = await renderIndexPage(config, posts);
+  const archiveHtml = await renderArchivePage(config, posts);
+
+  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"}`);
+
+  return posts;
+}
+
+async function copyDirectory(sourceDir, targetDir) {
+  await fs.mkdir(targetDir, { recursive: true });
+  const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDirectory(sourcePath, targetPath);
+    } else {
+      await fs.copyFile(sourcePath, targetPath);
+    }
+  }
+}
+
+async function copyStaticFiles(config, outputDir) {
+  try {
+    const entries = await fs.readdir(config.publicDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.name === "blog") {
+        continue;
+      }
+
+      if (["index.html", "archive.html", "sitemap.xml"].includes(entry.name)) {
+        continue;
+      }
+
+      const sourcePath = path.join(config.publicDir, entry.name);
+      const targetPath = path.join(outputDir, entry.name);
+
+      if (entry.isDirectory()) {
+        await copyDirectory(sourcePath, targetPath);
+      } else {
+        await fs.copyFile(sourcePath, targetPath);
+      }
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+function createOutputConfig(config, outputDir) {
+  return {
+    ...config,
+    publicDir: outputDir,
+    blogOutputDir: path.join(outputDir, "blog"),
+    sitemapPath: path.join(outputDir, "sitemap.xml"),
+    homePagePath: path.join(outputDir, "index.html"),
+    archivePagePath: path.join(outputDir, "archive.html"),
+    staticAssetsDir: path.join(outputDir, "assets")
+  };
+}
+
+export async function buildStaticSite(config, outputDir = config.buildDir) {
+  const outputConfig = createOutputConfig(config, outputDir);
+
+  await fs.rm(outputDir, { recursive: true, force: true });
+  await Promise.all([
+    fs.mkdir(outputConfig.publicDir, { recursive: true }),
+    fs.mkdir(outputConfig.blogOutputDir, { recursive: true })
+  ]);
+
+  await copyStaticFiles(config, outputDir);
+
+  const posts = await getAllPosts(config);
+  await Promise.all(
+    posts.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);
+
+  await fs.writeFile(outputConfig.homePagePath, indexHtml, "utf8");
+  await fs.writeFile(outputConfig.archivePagePath, archiveHtml, "utf8");
+  await generateSitemap(outputConfig, posts);
+
+  console.log(`[sharq] built ${posts.length} post${posts.length === 1 ? "" : "s"} to ${outputDir}`);
+  return { outputDir, posts };
+}
+
+export async function ensurePostGenerated(config, slug) {
+  assertValidSlug(slug);
+  const outputPath = path.join(config.blogOutputDir, `${slug}.html`);
+  const sourcePath = path.join(config.contentDir, `${slug}.md`);
+
+  try {
+    const [sourceStats, outputStats] = await Promise.all([fs.stat(sourcePath), fs.stat(outputPath)]);
+
+    if (sourceStats.mtimeMs > outputStats.mtimeMs) {
+      const post = await generatePost(config, slug);
+      return post.outputPath;
+    }
+
+    return outputPath;
+  } catch {
+    const post = await generatePost(config, slug);
+    return post.outputPath;
+  }
+}

package/lib/package-info.js

@@ -0,0 +1,8 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function readPackageVersion(packageRoot) {
+  const packageJsonPath = path.join(packageRoot, "package.json");
+  const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+  return packageJson.version;
+}