@uxfront/layer-docs 0.1.0

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@uxfront/layer-docs",
+  "version": "0.1.0",
+  "description": "Neutral, brandable Nuxt-layer documentation theme. Consumers extend it and supply their own branding, content and section topology.",
+  "keywords": [
+    "docs",
+    "documentation",
+    "docus",
+    "nuxt",
+    "nuxt-layer",
+    "theme"
+  ],
+  "homepage": "https://github.com/uxfront-com/uxfront/tree/main/packages/layer-docs#readme",
+  "bugs": "https://github.com/uxfront-com/uxfront/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uxfront-com/uxfront.git",
+    "directory": "packages/layer-docs"
+  },
+  "files": [
+    "app",
+    "i18n",
+    "modules",
+    "server",
+    "utils",
+    "nuxt.config.ts",
+    "tsconfig.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "types": "./nuxt.config.ts",
+  "exports": {
+    ".": {
+      "types": "./nuxt.config.ts",
+      "import": "./nuxt.config.ts"
+    },
+    "./content": {
+      "types": "./utils/content.ts",
+      "import": "./utils/content.ts"
+    },
+    "./app/assets/css/main.css": "./app/assets/css/main.css",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@vueuse/core": "^14.3.0",
+    "defu": "^6.1.4",
+    "git-url-parse": "^16.1.0",
+    "minimark": "^0.2.0",
+    "motion-v": "^1.7.2",
+    "pkg-types": "^2.3.1",
+    "scule": "^1.3.0",
+    "ufo": "^1.6.4"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "@nuxt/content": "^3.14.0",
+    "@nuxt/image": "^1.11.0",
+    "@nuxt/kit": "^4.4.8",
+    "@nuxt/scripts": "^0.11.13",
+    "@nuxt/ui": "^4.8.2",
+    "@nuxtjs/i18n": "^10.4.0",
+    "@nuxtjs/mdc": "^0.22.0",
+    "@nuxtjs/robots": "^6.1.1",
+    "@nuxtjs/sitemap": "^8.2.1",
+    "nuxt": "^4.4.8",
+    "nuxt-llms": "^0.2.0",
+    "posthog-js": "^1.386.6",
+    "tailwindcss": "^4.3.1",
+    "typescript": "^6.0.3",
+    "vue": "^3.5.38"
+  },
+  "peerDependenciesMeta": {
+    "@nuxtjs/i18n": {
+      "optional": true
+    },
+    "@nuxtjs/mdc": {
+      "optional": true
+    },
+    "posthog-js": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "postinstall": "nuxt prepare"
+  }
+}

package/server/plugins/llms-redirect.ts

@@ -0,0 +1,60 @@
+import type { H3Event } from "h3";
+import { withoutTrailingSlash } from "ufo";
+
+/**
+ * Serve `/llms.txt` from the homepage for AI agents and crawlers.
+ *
+ * Human browsers still get the rendered homepage; only clients that ask for
+ * markdown (`Accept: text/markdown`) or identify as `curl` are redirected to
+ * the `nuxt-llms` entry point. This mirrors Docus's agent-friendly behaviour
+ * but works across Nitro presets (we deploy the node-server output), where the
+ * upstream Vercel-config rewrite does not apply.
+ *
+ * It runs on the `request` hook rather than as route middleware so it fires
+ * before Nitro's public-asset handler serves the prerendered homepage — route
+ * middleware would never see a request for a statically generated page.
+ */
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook("request", (event) => {
+    if (event.method !== "GET" && event.method !== "HEAD") {
+      return;
+    }
+
+    const path = withoutTrailingSlash(event.path.split("?")[0]) || "/";
+    if (!isRootPath(event, path)) {
+      return;
+    }
+
+    const accept = getHeader(event, "accept") ?? "";
+    const userAgent = getHeader(event, "user-agent") ?? "";
+
+    const wantsMarkdown = accept.includes("text/markdown");
+    const isCurl = /^curl\//i.test(userAgent);
+
+    if (wantsMarkdown || isCurl) {
+      return sendRedirect(event, "/llms.txt", 302);
+    }
+  });
+});
+
+/**
+ * True for `/` and, when i18n is enabled, each locale homepage (e.g. `/en`).
+ */
+function isRootPath(event: H3Event, path: string) {
+  if (path === "/") {
+    return true;
+  }
+
+  const i18n = useRuntimeConfig(event).public.i18n as
+    | { locales?: (string | { code: string })[] }
+    | undefined;
+
+  if (!i18n?.locales) {
+    return false;
+  }
+
+  return i18n.locales.some((locale) => {
+    const code = typeof locale === "string" ? locale : locale.code;
+    return path === `/${code}`;
+  });
+}

package/server/routes/raw/[...slug].md.get.ts

@@ -0,0 +1,74 @@
+import { withLeadingSlash } from "ufo";
+import { stringify } from "minimark/stringify";
+import { queryCollection } from "@nuxt/content/nitro";
+import type { Collections } from "@nuxt/content";
+import { DOCS_SECTIONS } from "~/constants/sections";
+
+export default eventHandler(async (event) => {
+  const slug = getRouterParams(event)["slug.md"];
+  if (!slug?.endsWith(".md")) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: "Page not found",
+      fatal: true,
+    });
+  }
+
+  const path = withLeadingSlash(slug.replace(".md", ""));
+  const config = useRuntimeConfig(event).public;
+
+  const pathSegments = path.split("/").filter(Boolean);
+  let localeSegment: string | undefined;
+  let sectionIndex = 1; // expect /docs/<section>/...
+
+  const i18n = config.i18n as
+    | { locales?: (string | { code: string })[]; defaultLocale?: string }
+    | undefined;
+
+  if (i18n?.locales) {
+    const availableLocales = i18n.locales.map((locale) =>
+      typeof locale === "string" ? locale : locale.code,
+    );
+    const firstSegment = pathSegments[0];
+    if (firstSegment && availableLocales.includes(firstSegment)) {
+      localeSegment = firstSegment;
+      sectionIndex = 2;
+    } else if (i18n.defaultLocale) {
+      localeSegment = i18n.defaultLocale;
+    }
+  }
+
+  const sectionSlug = pathSegments[sectionIndex];
+  const section = DOCS_SECTIONS.find((s) => s.slug === sectionSlug);
+  if (!section) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: "Page not found",
+      fatal: true,
+    });
+  }
+
+  const collectionName = localeSegment
+    ? `docs_${section.key}_${localeSegment}`
+    : `docs_${section.key}`;
+
+  const page = await queryCollection(event, collectionName as keyof Collections)
+    .path(path)
+    .first();
+  if (!page) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: "Page not found",
+      fatal: true,
+    });
+  }
+
+  // Add title and description to the top of the page if missing
+  if (page.body.value[0]?.[0] !== "h1") {
+    page.body.value.unshift(["blockquote", {}, page.description]);
+    page.body.value.unshift(["h1", {}, page.title]);
+  }
+
+  setHeader(event, "Content-Type", "text/markdown; charset=utf-8");
+  return stringify({ ...page.body, type: "minimark" }, { format: "markdown/html" });
+});

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "files": [],
+  "references": [
+    {
+      "path": "./.nuxt/tsconfig.app.json"
+    },
+    {
+      "path": "./.nuxt/tsconfig.server.json"
+    },
+    {
+      "path": "./.nuxt/tsconfig.shared.json"
+    },
+    {
+      "path": "./.nuxt/tsconfig.node.json"
+    }
+  ]
+}

package/utils/content.ts

@@ -0,0 +1,118 @@
+import type { DefinedCollection } from "@nuxt/content";
+import { defineContentConfig, defineCollection, z } from "@nuxt/content";
+import { useNuxt } from "@nuxt/kit";
+
+/**
+ * Minimal structural shape of a documentation section descriptor. The consuming
+ * app owns the concrete `DOCS_SECTIONS` array (and may extend each entry with
+ * extra fields like `icon`/`label` used by the runtime nav); this helper only
+ * reads the fields it needs to build Nuxt Content collections.
+ */
+export interface DocsSectionDescriptor {
+  /** Stable collection key, e.g. "guide" → collection `docs_guide`. */
+  key: string;
+  /** URL segment under `/docs/<slug>`. */
+  slug: string;
+  /** Human label, used as a fallback nav title. */
+  label: string;
+  /** Source folder(s) under `content/docs/`. String or list. */
+  folder: string | string[];
+  /**
+   * When `folder` is a list, the index whose pages mount at the section root
+   * (`/docs/<slug>`) instead of `/docs/<slug>/<folder>`. Defaults to none.
+   */
+  rootFolder?: number;
+}
+
+const createDocsSchema = () =>
+  z.object({
+    links: z
+      .array(
+        z.object({
+          label: z.string(),
+          icon: z.string(),
+          to: z.string(),
+          target: z.string().optional(),
+        }),
+      )
+      .optional(),
+  });
+
+const buildDocsSource = (section: DocsSectionDescriptor, pathPrefix = "", urlPrefix = "") => {
+  const folders = Array.isArray(section.folder) ? section.folder : [section.folder];
+  const baseUrl = `${urlPrefix}/docs/${section.slug}`;
+
+  if (folders.length === 1) {
+    return {
+      include: `${pathPrefix}docs/${folders[0]}/**/*.{md,yml}`,
+      prefix: baseUrl,
+    };
+  }
+
+  const rootIndex = typeof section.rootFolder === "number" ? section.rootFolder : -1;
+
+  return folders.map((folder, index) => ({
+    include: `${pathPrefix}docs/${folder}/**/*.{md,yml}`,
+    prefix: index === rootIndex ? baseUrl : `${baseUrl}/${folder.replace(/^\d+\./, "")}`,
+  }));
+};
+
+/**
+ * Builds the Nuxt Content configuration for a documentation site from a list of
+ * section descriptors. A consumer's `content.config.ts` becomes a one-liner:
+ *
+ * ```ts
+ * import { defineDocsCollections } from "@uxfront/layer-docs/content";
+ * import { DOCS_SECTIONS } from "./app/constants/sections";
+ * export default defineDocsCollections(DOCS_SECTIONS);
+ * ```
+ *
+ * Produces one `landing` collection (root markdown) plus one `docs_<key>`
+ * collection per section. When `@nuxtjs/i18n` is configured with `locales`, the
+ * collections are generated per-locale (`landing_<code>`, `docs_<key>_<code>`)
+ * and sourced from a matching `content/<code>/` subtree; otherwise a single flat
+ * set is produced. The section topology and content stay in the consuming app.
+ */
+export function defineDocsCollections(sections: DocsSectionDescriptor[]) {
+  const { options } = useNuxt();
+  const locales = options.i18n?.locales;
+
+  let collections: Record<string, DefinedCollection>;
+
+  if (locales && Array.isArray(locales) && locales.length > 0) {
+    collections = {};
+    for (const locale of locales) {
+      const code = typeof locale === "string" ? locale : locale.code;
+
+      collections[`landing_${code}`] = defineCollection({
+        type: "page",
+        source: [{ include: `${code}/*.md` }],
+      });
+
+      for (const section of sections) {
+        collections[`docs_${section.key}_${code}`] = defineCollection({
+          type: "page",
+          source: buildDocsSource(section, `${code}/`, `/${code}`),
+          schema: createDocsSchema(),
+        });
+      }
+    }
+  } else {
+    collections = {
+      landing: defineCollection({
+        type: "page",
+        source: [{ include: "*.md" }],
+      }),
+    };
+
+    for (const section of sections) {
+      collections[`docs_${section.key}`] = defineCollection({
+        type: "page",
+        source: buildDocsSource(section),
+        schema: createDocsSchema(),
+      });
+    }
+  }
+
+  return defineContentConfig({ collections });
+}

package/utils/git.ts

@@ -0,0 +1,114 @@
+import { execSync } from "node:child_process";
+import { readGitConfig } from "pkg-types";
+import gitUrlParse from "git-url-parse";
+
+export interface GitInfo {
+  // Repository name
+  name: string;
+  // Repository owner/organization
+  owner: string;
+  // Repository URL
+  url: string;
+}
+
+export function getGitBranch() {
+  const envName =
+    process.env.CF_PAGES_BRANCH ||
+    process.env.CI_COMMIT_BRANCH ||
+    process.env.VERCEL_GIT_COMMIT_REF ||
+    process.env.BRANCH ||
+    process.env.GITHUB_REF_NAME;
+
+  if (envName && envName !== "HEAD") {
+    return envName;
+  }
+  try {
+    const branch = execSync("git rev-parse --abbrev-ref HEAD", {
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .toString()
+      .trim();
+    if (branch && branch !== "HEAD") {
+      return branch;
+    }
+  } catch {
+    // Ignore error
+  }
+
+  return "main";
+}
+
+export async function getLocalGitInfo(rootDir: string): Promise<GitInfo | undefined> {
+  const remote = await getLocalGitRemote(rootDir);
+  if (!remote) {
+    return;
+  }
+
+  // https://www.npmjs.com/package/git-url-parse#clipboard-example
+  const { name, owner, source } = gitUrlParse(remote);
+  const url = `https://${source}/${owner}/${name}`;
+
+  return {
+    name,
+    owner,
+    url,
+  };
+}
+
+async function getLocalGitRemote(dir: string): Promise<string | undefined> {
+  try {
+    const parsed = await readGitConfig(dir);
+    if (!parsed) {
+      return;
+    }
+    return parsed.remote?.["origin"]?.url;
+  } catch {
+    // Ignore error
+  }
+}
+
+export function getGitEnv(): GitInfo {
+  // https://github.com/unjs/std-env/issues/59
+  const envInfo = {
+    // Provider
+    provider:
+      process.env.VERCEL_GIT_PROVIDER || // vercel
+      (process.env.GITHUB_SERVER_URL ? "github" : undefined) || // github
+      "",
+    // Owner
+    owner:
+      process.env.VERCEL_GIT_REPO_OWNER || // vercel
+      process.env.GITHUB_REPOSITORY_OWNER || // github
+      process.env.CI_PROJECT_PATH?.split("/").shift() || // gitlab
+      "",
+    // Name
+    name:
+      process.env.VERCEL_GIT_REPO_SLUG ||
+      process.env.GITHUB_REPOSITORY?.split("/").pop() || // github
+      process.env.CI_PROJECT_PATH?.split("/").splice(1).join("/") || // gitlab
+      "",
+    // Url
+    url: process.env.REPOSITORY_URL || "", // netlify
+  };
+
+  if (!envInfo.url && envInfo.provider && envInfo.owner && envInfo.name) {
+    envInfo.url = `https://${envInfo.provider}.com/${envInfo.owner}/${envInfo.name}`;
+  }
+
+  // If only url available (ex: Netlify)
+  if (!envInfo.name && !envInfo.owner && envInfo.url) {
+    try {
+      const { name, owner } = gitUrlParse(envInfo.url);
+      envInfo.name = name;
+      envInfo.owner = owner;
+    } catch {
+      // Ignore error
+    }
+  }
+
+  return {
+    name: envInfo.name,
+    owner: envInfo.owner,
+    url: envInfo.url,
+  };
+}

package/utils/meta.ts

@@ -0,0 +1,28 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+export function inferSiteURL() {
+  // https://github.com/unjs/std-env/issues/59
+  return (
+    process.env.NUXT_SITE_URL ||
+    (process.env.NEXT_PUBLIC_VERCEL_URL && `https://${process.env.NEXT_PUBLIC_VERCEL_URL}`) || // Vercel
+    process.env.URL || // Netlify
+    process.env.CI_PAGES_URL || // Gitlab Pages
+    process.env.CF_PAGES_URL // Cloudflare Pages
+  );
+}
+
+export async function getPackageJsonMetadata(dir: string) {
+  try {
+    const packageJson = await readFile(resolve(dir, "package.json"), "utf-8");
+    const parsed = JSON.parse(packageJson);
+    return {
+      name: parsed.name,
+      description: parsed.description,
+    };
+  } catch {
+    return {
+      name: "docs",
+    };
+  }
+}