create-opendocs 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# create-opendocs
+
+`create-opendocs` scaffolds a new OpenDocs-powered documentation site.
+
+## What It Creates
+
+The generated project is a Next.js docs app with:
+
+- File-based content in `content/`
+- Sidebar navigation configured in `content/config.json`
+- Markdown and MDX page support
+- A footer CTA block driven by config
+- Static page generation and sitemap support
+
+## Usage
+
+Create a new project:
+
+```bash
+npx create-opendocs my-docs
+```
+
+Create a project with custom defaults:
+
+```bash
+npx create-opendocs my-docs --site-name "My Docs" --support-email docs@example.com --site-url https://docs.example.com
+```
+
+Then run:
+
+```bash
+cd my-docs
+npm run dev
+```
+
+## Options
+
+- `--site-name <name>`: visible docs/site name
+- `--description <text>`: metadata description
+- `--support-email <email>`: footer support email
+- `--site-url <url>`: default public site URL used by the starter
+- `--no-install`: skip `npm install`
+- `--force`: allow copying into a non-empty directory
+
+## Repository Layout
+
+- `src/create-opendocs.js`: the CLI entrypoint
+- `template/`: the Next.js starter app that gets copied into new projects
+
+## Local Development
+
+Dry-run the published package contents:
+
+```bash
+npm run pack:dry-run
+```
+
+Install and validate the template app:
+
+```bash
+npm run template:install
+npm run template:lint
+npm run template:build
+```
+
+## Publishing
+
+When you're ready to publish:
+
+```bash
+npm publish --access public
+```
+
+Before publishing, it's worth running:
+
+```bash
+npm run pack:dry-run
+```

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "create-opendocs",
+  "version": "0.1.0",
+  "description": "Scaffold a new OpenDocs documentation site.",
+  "license": "MIT",
+  "preferGlobal": true,
+  "bin": {
+    "create-opendocs": "./src/create-opendocs.js"
+  },
+  "files": [
+    "src",
+    "template"
+  ],
+  "scripts": {
+    "pack:dry-run": "npm pack --dry-run",
+    "template:install": "npm --prefix template install",
+    "template:lint": "npm --prefix template run lint",
+    "template:build": "npm --prefix template run build"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "keywords": [
+    "docs",
+    "nextjs",
+    "starter",
+    "scaffold"
+  ]
+}

package/src/create-opendocs.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const TEMPLATE_DIR = path.join(__dirname, "..", "template");
+const TEXT_FILE_EXTENSIONS = new Set([
+  ".css",
+  ".gitignore",
+  ".js",
+  ".json",
+  ".md",
+  ".mdx",
+  ".mjs",
+  ".ts",
+  ".tsx",
+  ".txt",
+]);
+
+function printUsage() {
+  console.log(`Usage: create-opendocs <project-directory> [options]
+
+Options:
+  --site-name <name>         Override the visible docs/site name
+  --description <text>       Override the site description
+  --support-email <email>    Set the footer contact email
+  --site-url <url>           Set NEXT_PUBLIC_SITE_URL in the starter content
+  --no-install               Skip npm install in the generated project
+  --force                    Allow copying into a non-empty directory
+`);
+}
+
+function parseArgs(argv) {
+  const options = {
+    install: true,
+    force: false,
+  };
+  let targetDir = null;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (!arg.startsWith("--")) {
+      targetDir = targetDir || arg;
+      continue;
+    }
+
+    if (arg === "--no-install") {
+      options.install = false;
+      continue;
+    }
+
+    if (arg === "--force") {
+      options.force = true;
+      continue;
+    }
+
+    const nextValue = argv[i + 1];
+    if (!nextValue || nextValue.startsWith("--")) {
+      throw new Error(`Missing value for ${arg}`);
+    }
+
+    if (arg === "--site-name") {
+      options.siteName = nextValue;
+    } else if (arg === "--description") {
+      options.description = nextValue;
+    } else if (arg === "--support-email") {
+      options.supportEmail = nextValue;
+    } else if (arg === "--site-url") {
+      options.siteUrl = nextValue;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    i += 1;
+  }
+
+  return { options, targetDir };
+}
+
+function toTitleCase(value) {
+  return value
+    .replace(/[-_]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join(" ");
+}
+
+function toPackageName(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9-_]/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-+|-+$/g, "") || "my-docs";
+}
+
+function ensureEmptyTarget(targetPath, force) {
+  if (!fs.existsSync(targetPath)) {
+    fs.mkdirSync(targetPath, { recursive: true });
+    return;
+  }
+
+  const files = fs.readdirSync(targetPath);
+  if (files.length === 0 || force) {
+    return;
+  }
+
+  throw new Error(`Target directory is not empty: ${targetPath}`);
+}
+
+function copyDirectory(sourceDir, destinationDir) {
+  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.name === "node_modules" || entry.name === ".next") {
+      continue;
+    }
+
+    const sourcePath = path.join(sourceDir, entry.name);
+    const destinationPath = path.join(destinationDir, entry.name);
+
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destinationPath, { recursive: true });
+      copyDirectory(sourcePath, destinationPath);
+      continue;
+    }
+
+    fs.copyFileSync(sourcePath, destinationPath);
+  }
+}
+
+function isTextFile(filePath) {
+  const extension = path.extname(filePath);
+  return TEXT_FILE_EXTENSIONS.has(extension) || path.basename(filePath) === ".gitignore";
+}
+
+function replaceTokensInDirectory(directoryPath, replacements) {
+  const entries = fs.readdirSync(directoryPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(directoryPath, entry.name);
+
+    if (entry.isDirectory()) {
+      replaceTokensInDirectory(fullPath, replacements);
+      continue;
+    }
+
+    if (!isTextFile(fullPath)) {
+      continue;
+    }
+
+    let contents = fs.readFileSync(fullPath, "utf8");
+    for (const [token, value] of Object.entries(replacements)) {
+      contents = contents.split(token).join(value);
+    }
+    fs.writeFileSync(fullPath, contents);
+  }
+}
+
+function runInstall(targetPath) {
+  const result = spawnSync("npm", ["install"], {
+    cwd: targetPath,
+    stdio: "inherit",
+    shell: true,
+  });
+
+  if (result.status !== 0) {
+    throw new Error("npm install failed");
+  }
+}
+
+function main() {
+  try {
+    const { options, targetDir } = parseArgs(process.argv.slice(2));
+
+    if (!targetDir) {
+      printUsage();
+      process.exit(1);
+    }
+
+    const targetPath = path.resolve(process.cwd(), targetDir);
+    const projectDirectoryName = path.basename(targetPath);
+    const projectName = toPackageName(projectDirectoryName);
+    const siteName = options.siteName || toTitleCase(projectDirectoryName);
+    const description = options.description || `${siteName} documentation`;
+    const supportEmail = options.supportEmail || "support@example.com";
+    const siteUrl = options.siteUrl || "https://docs.example.com";
+
+    ensureEmptyTarget(targetPath, options.force);
+    copyDirectory(TEMPLATE_DIR, targetPath);
+    replaceTokensInDirectory(targetPath, {
+      "__PROJECT_NAME__": projectName,
+      "__SITE_NAME__": siteName,
+      "__SITE_DESCRIPTION__": description,
+      "__SUPPORT_EMAIL__": supportEmail,
+      "__SITE_URL__": siteUrl,
+    });
+
+    if (options.install) {
+      console.log(`Installing dependencies in ${targetPath}...`);
+      runInstall(targetPath);
+    }
+
+    console.log("");
+    console.log(`OpenDocs project created at ${targetPath}`);
+    console.log("");
+    console.log("Next steps:");
+    console.log(`  cd ${targetDir}`);
+    if (!options.install) {
+      console.log("  npm install");
+    }
+    console.log("  npm run dev");
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+main();

package/template/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["next/core-web-vitals", "next/typescript"]
+}

package/template/Dockerfile

@@ -0,0 +1,48 @@
+FROM node:20-alpine AS base
+
+# Install dependencies only when needed
+FROM base AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+# Install dependencies based on the preferred package manager
+COPY package.json package-lock.json* ./
+RUN npm ci
+
+# Rebuild the source code only when needed
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# Next.js telemetry is disabled
+ENV NEXT_TELEMETRY_DISABLED 1
+
+RUN npm run build
+
+# Production image, copy all the files and run next
+FROM base AS runner
+WORKDIR /app
+
+ENV NODE_ENV production
+ENV NEXT_TELEMETRY_DISABLED 1
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+# Set the correct permission for prerender cache
+RUN mkdir .next
+RUN chown nextjs:nodejs .next
+
+# Leverage output traces to reduce image size
+# https://nextjs.org/docs/advanced-features/output-file-tracing
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE 3000
+ENV PORT 3000
+ENV HOSTNAME "0.0.0.0"
+
+CMD ["node", "server.js"]

package/template/README.md

@@ -0,0 +1,86 @@
+# __SITE_NAME__
+
+__SITE_NAME__ is a lightweight Next.js documentation site powered by OpenDocs.
+
+## Setup
+
+1. Install dependencies:
+
+```bash
+npm install
+```
+
+2. Start the development server:
+
+```bash
+npm run dev
+```
+
+3. Open `http://localhost:3000`.
+
+4. Optional: set your production site URL for sitemap generation:
+
+```bash
+$env:NEXT_PUBLIC_SITE_URL="__SITE_URL__"
+```
+
+## What The Project Does
+
+- Loads docs from the `content/` folder
+- Builds the sidebar from `content/config.json`
+- Renders Markdown and MDX pages automatically from file paths
+- Shows an optional footer CTA from config
+- Generates a sitemap from your docs pages
+
+## Navigation
+
+Navigation is configured in `content/config.json`.
+
+Example:
+
+```json
+{
+  "homepage": "index.md",
+  "sidebar": [
+    {
+      "title": "Getting Started",
+      "items": [
+        "index.md",
+        "guides/getting-started.md"
+      ]
+    }
+  ]
+}
+```
+
+How it works:
+
+- `homepage` controls which file renders at `/`
+- each `sidebar` group becomes a visible section in the left navigation
+- each `items` entry should point to a file inside `content/`
+- sidebar order also controls the "Up next" order at the bottom of pages
+
+## Footer Config
+
+The footer CTA lives under `contactSupport` in `content/config.json`.
+
+Example:
+
+```json
+{
+  "contactSupport": {
+    "title": "Need help?",
+    "description": "Contact the docs team if anything is unclear.",
+    "buttonText": "Email us",
+    "buttonLink": "mailto:docs@example.com"
+  }
+}
+```
+
+## Useful Files
+
+- `content/config.json`: homepage, sidebar, and footer configuration
+- `content/index.md`: homepage content
+- `src/lib/docs.ts`: file loading and sidebar generation
+- `src/app/[[...slug]]/page.tsx`: page rendering and metadata
+- `src/components/Sidebar.tsx`: sidebar UI

package/template/content/config.json

@@ -0,0 +1,18 @@
+{
+  "homepage": "index.md",
+  "sidebar": [
+    {
+      "title": "Getting Started",
+      "items": [
+        "index.md",
+        "guides/getting-started.md"
+      ]
+    }
+  ],
+  "contactSupport": {
+    "title": "Was this helpful?",
+    "description": "Reach out to support if you need assistance or are stuck.",
+    "buttonText": "Contact Support",
+    "buttonLink": "mailto:__SUPPORT_EMAIL__"
+  }
+}

package/template/content/guides/getting-started.md

@@ -0,0 +1,21 @@
+# Getting Started
+
+## Run Locally
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Start the dev server:
+
+```bash
+npm run dev
+```
+
+Open `http://localhost:3000` to view your docs site.
+
+## Add Pages
+
+Create Markdown or MDX files in `content/`, then list them in `content/config.json` if you want them to appear in the sidebar.

package/template/content/index.md

@@ -0,0 +1,11 @@
+# Welcome to __SITE_NAME__
+
+__SITE_NAME__ is your new documentation site powered by OpenDocs.
+
+## Start Here
+
+- Edit this homepage in `content/index.md`
+- Update the sidebar in `content/config.json`
+- Add new Markdown or MDX pages under `content/`
+
+When you're ready, publish the site with your own branding, content, and links.

package/template/next.config.mjs

@@ -0,0 +1,5 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+    output: "standalone",
+};
+export default nextConfig;