@uxfront/layer-docs 0.1.0

package/app/pages/[[lang]]/docs/[section]/[...slug].vue

@@ -0,0 +1,171 @@
+<script setup lang="ts">
+import { kebabCase } from "scule";
+import type { ContentNavigationItem, Collections, PageCollectionItemBase } from "@nuxt/content";
+
+type DocsPageItem = PageCollectionItemBase & {
+  links?: Array<{
+    label: string;
+    icon: string;
+    to: string;
+    target?: string;
+  }>;
+  seo?: { title?: string; description?: string };
+};
+import { findPageHeadline } from "@nuxt/content/utils";
+
+definePageMeta({
+  layout: "default",
+});
+
+const route = useRoute();
+const { locale, isEnabled, t } = useDocusI18n();
+const appConfig = useAppConfig();
+const navigationMap = inject<Ref<Record<string, ContentNavigationItem[]>>>("navigation");
+
+const sectionSlug = computed(() => route.params.section as string);
+const section = computed(() => findDocsSectionBySlug(sectionSlug.value));
+
+if (!section.value) {
+  throw createError({
+    statusCode: 404,
+    statusMessage: "Page not found",
+    fatal: true,
+  });
+}
+
+const collectionName = computed(() =>
+  isEnabled.value ? `docs_${section.value!.key}_${locale.value}` : `docs_${section.value!.key}`,
+);
+
+const navigation = computed(() => navigationMap?.value?.[section.value!.key] ?? []);
+
+const [{ data: page }, { data: surround }] = await Promise.all([
+  useAsyncData(
+    kebabCase(route.path),
+    () =>
+      queryCollection(collectionName.value as keyof Collections)
+        .path(route.path)
+        .first() as Promise<DocsPageItem>,
+  ),
+  useAsyncData(`${kebabCase(route.path)}-surround`, () => {
+    return queryCollectionItemSurroundings(collectionName.value as keyof Collections, route.path, {
+      fields: ["description"],
+    });
+  }),
+]);
+
+if (!page.value) {
+  throw createError({
+    statusCode: 404,
+    statusMessage: "Page not found",
+    fatal: true,
+  });
+}
+
+// Add the page path to the prerender list
+addPrerenderPath(`/raw${route.path}.md`);
+
+const title = page.value.seo?.title || page.value.title;
+const description = page.value.seo?.description || page.value.description;
+
+useSeoMeta({
+  title,
+  ogTitle: title,
+  description,
+  ogDescription: description,
+});
+
+const headline = ref(findPageHeadline(navigation.value, page.value?.path));
+watch(
+  () => navigation.value,
+  () => {
+    headline.value = findPageHeadline(navigation.value, page.value?.path) || headline.value;
+  },
+);
+
+const github = computed(() => (appConfig.github ? appConfig.github : null));
+
+const editLink = computed(() => {
+  if (!github.value) {
+    return;
+  }
+
+  return [
+    github.value.url,
+    "edit",
+    github.value.branch,
+    github.value.rootDir,
+    "content",
+    `${page.value?.stem}.${page.value?.extension}`,
+  ]
+    .filter(Boolean)
+    .join("/");
+});
+</script>
+
+<template>
+  <UPage v-if="page">
+    <UPageHeader
+      :title="page.title"
+      :description="page.description"
+      :headline="headline"
+      :ui="{
+        wrapper: 'flex-row items-center flex-wrap justify-between',
+      }"
+    >
+      <template #links>
+        <UButton
+          v-for="(link, index) in (page as DocsPageItem).links"
+          :key="index"
+          size="sm"
+          v-bind="link"
+        />
+
+        <DocsPageHeaderLinks />
+      </template>
+    </UPageHeader>
+
+    <UPageBody>
+      <ContentRenderer v-if="page" :value="page" />
+
+      <USeparator>
+        <div v-if="github" class="flex items-center gap-2 text-sm text-muted">
+          <UButton
+            variant="link"
+            color="neutral"
+            :to="editLink"
+            target="_blank"
+            icon="i-lucide-pen"
+            :ui="{ leadingIcon: 'size-4' }"
+          >
+            {{ t("docs.edit") }}
+          </UButton>
+          <span>{{ t("common.or") }}</span>
+          <UButton
+            variant="link"
+            color="neutral"
+            :to="`${github.url}/issues/new/choose`"
+            target="_blank"
+            icon="i-lucide-alert-circle"
+            :ui="{ leadingIcon: 'size-4' }"
+          >
+            {{ t("docs.report") }}
+          </UButton>
+        </div>
+      </USeparator>
+      <UContentSurround :surround="surround" />
+    </UPageBody>
+
+    <template v-if="page?.body?.toc?.links?.length" #right>
+      <UContentToc
+        highlight
+        :title="appConfig.toc?.title || t('docs.toc')"
+        :links="page.body?.toc?.links"
+      >
+        <template #bottom>
+          <DocsAsideRightBottom />
+        </template>
+      </UContentToc>
+    </template>
+  </UPage>
+</template>

package/app/plugins/i18n.ts

@@ -0,0 +1,21 @@
+export default defineNuxtPlugin(() => {
+  // Consumers opt out via `app.config` (`i18nRedirect.enabled: false`).
+  if (!useAppConfig().i18nRedirect?.enabled) {
+    return;
+  }
+
+  const nuxtApp = useNuxtApp();
+
+  const i18nConfig = nuxtApp.$config.public.i18n as { defaultLocale?: string } | undefined;
+  if (!i18nConfig) {
+    return;
+  }
+
+  addRouteMiddleware((to) => {
+    if (to.path === "/") {
+      const cookieLocale = useCookie("i18n_redirected").value || i18nConfig.defaultLocale || "en";
+
+      return navigateTo(`/${cookieLocale}`);
+    }
+  });
+});

package/app/plugins/posthog.client.ts

@@ -0,0 +1,31 @@
+import type { ConfigDefaults } from "posthog-js";
+import posthog from "posthog-js";
+import { defineNuxtPlugin } from "#app";
+
+export default defineNuxtPlugin(() => {
+  if (import.meta.dev) {
+    return;
+  }
+
+  // Consumers opt out via `app.config` (`analytics.enabled: false`).
+  if (!useAppConfig().analytics?.enabled) {
+    return;
+  }
+
+  const runtimeConfig = useRuntimeConfig();
+
+  const posthogClient = posthog.init(runtimeConfig.public.posthog.key, {
+    api_host: runtimeConfig.public.posthog.host,
+    defaults: runtimeConfig.public.posthog.defaults as ConfigDefaults,
+    person_profiles: "identified_only", // or 'always' to create profiles for anonymous users as well
+    loaded: (posthog) => {
+      if (import.meta.env.MODE === "development") posthog.debug();
+    },
+  });
+
+  return {
+    provide: {
+      posthog: () => posthogClient,
+    },
+  };
+});

package/app/types/non-route-categories.ts

@@ -0,0 +1,12 @@
+export interface NonRouteCategoryMeta {
+  title: string;
+  icon?: string | false;
+  defaultOpen?: boolean;
+  order: number;
+}
+
+declare module "nuxt/schema" {
+  interface AppConfig {
+    nonRouteCategories?: Record<string, NonRouteCategoryMeta>;
+  }
+}

package/app/utils/flattenNavigation.ts

@@ -0,0 +1,22 @@
+import type { ContentNavigationItem } from "@nuxt/content";
+
+/**
+ * Flatten navigation items that are false-positive groups.
+ * Nuxt Content's index detection regex matches filenames containing "index"
+ * as a substring (e.g. "z-index"), incorrectly nesting them as groups.
+ * This flattens groups with a single child sharing the same path.
+ */
+export function flattenNavigation(items: ContentNavigationItem[]): ContentNavigationItem[] {
+  return items.map((item) => {
+    if (item.children?.length === 1 && item.children[0]?.path === item.path) {
+      const { children: _, ...parent } = item;
+      return { ...parent, ...item.children[0], children: undefined };
+    }
+
+    if (item.children?.length) {
+      return { ...item, children: flattenNavigation(item.children) };
+    }
+
+    return item;
+  });
+}

package/app/utils/foldNonRouteCategories.ts

@@ -0,0 +1,47 @@
+import type { ContentNavigationItem } from "@nuxt/content";
+import type { NonRouteCategoryMeta } from "~/types/non-route-categories";
+
+/**
+ * Rebuilds the sidebar grouping for non-route categories.
+ *
+ * Pages under a `route: false` folder are flattened in the URL, so the native
+ * navigation tree lists them as direct children with the category level gone.
+ * This re-nests each such page under a synthetic group node (rendered as a
+ * non-navigating accordion header), matching pages to categories by `stem`.
+ */
+export function foldNonRouteCategories(
+  items: ContentNavigationItem[],
+  categories: Record<string, NonRouteCategoryMeta>,
+): ContentNavigationItem[] {
+  return items.map((node) => {
+    if (!node.children?.length) {
+      return node;
+    }
+    const passthrough: ContentNavigationItem[] = [];
+    const groups = new Map<
+      string,
+      { meta: NonRouteCategoryMeta; children: ContentNavigationItem[] }
+    >();
+    for (const child of node.children) {
+      const dir = child.stem ? child.stem.split("/").slice(0, -1).join("/") : "";
+      const meta = categories[dir];
+      if (meta && child.page !== false) {
+        const group = groups.get(dir) ?? { meta, children: [] };
+        group.children.push(child);
+        groups.set(dir, group);
+      } else {
+        passthrough.push(foldNonRouteCategories([child], categories)[0]!);
+      }
+    }
+    const groupNodes = [...groups.values()]
+      .sort((a, b) => a.meta.order - b.meta.order || a.meta.title.localeCompare(b.meta.title))
+      .map(({ meta, children }) => ({
+        title: meta.title,
+        ...(meta.icon ? { icon: meta.icon } : {}),
+        ...(meta.defaultOpen !== undefined ? { defaultOpen: meta.defaultOpen } : {}),
+        page: false as const,
+        children,
+      })) as ContentNavigationItem[];
+    return { ...node, children: [...passthrough, ...groupNodes] };
+  });
+}

package/app/utils/prerender.ts

@@ -0,0 +1,9 @@
+export const addPrerenderPath = (path: string) => {
+  const event = useRequestEvent();
+  if (event) {
+    event.node.res.setHeader(
+      "x-nitro-prerender",
+      [event.node.res.getHeader("x-nitro-prerender"), path].filter(Boolean).join(","),
+    );
+  }
+};

package/i18n/locales/en.json

@@ -0,0 +1,22 @@
+{
+  "common": {
+    "or": "or",
+    "error": {
+      "title": "Page not found",
+      "description": "We are sorry but this page could not be found."
+    }
+  },
+  "docs": {
+    "copy": {
+      "page": "Copy page",
+      "link": "Copy Markdown page",
+      "view": "View as Markdown",
+      "gpt": "Open in ChatGPT",
+      "claude": "Open in Claude"
+    },
+    "links": "Community",
+    "toc": "On this page",
+    "report": "Report an issue",
+    "edit": "Edit this page"
+  }
+}

package/modules/config.ts

@@ -0,0 +1,122 @@
+import { createResolver, defineNuxtModule } from "@nuxt/kit";
+import { defu } from "defu";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { inferSiteURL, getPackageJsonMetadata } from "../utils/meta";
+import { getGitBranch, getGitEnv, getLocalGitInfo } from "../utils/git";
+
+export default defineNuxtModule({
+  meta: {
+    name: "config",
+  },
+  async setup(_options, nuxt) {
+    const dir = nuxt.options.rootDir;
+    const url = inferSiteURL();
+    const meta = await getPackageJsonMetadata(dir);
+    const gitInfo = (await getLocalGitInfo(dir)) || getGitEnv();
+    const site = nuxt.options.site;
+    const siteName =
+      (typeof site === "object" ? site.name : undefined) || meta.name || gitInfo?.name || "";
+
+    nuxt.options.llms = defu(nuxt.options.llms, {
+      domain: url,
+      title: siteName,
+      description: meta.description || "",
+      full: {
+        title: siteName,
+        description: meta.description || "",
+      },
+    });
+
+    nuxt.options.site = defu(nuxt.options.site, {
+      url,
+      name: siteName,
+      debug: false,
+    }) as typeof nuxt.options.site;
+
+    nuxt.options.appConfig.header = defu(nuxt.options.appConfig.header, {
+      title: siteName,
+    });
+
+    nuxt.options.appConfig.seo = defu(nuxt.options.appConfig.seo, {
+      titleTemplate: `%s - ${siteName}`,
+      title: siteName,
+      description: meta.description || "",
+    });
+
+    nuxt.options.appConfig.github = defu(nuxt.options.appConfig.github, {
+      owner: gitInfo?.owner,
+      name: gitInfo?.name,
+      url: gitInfo?.url,
+      branch: getGitBranch(),
+    });
+
+    /*
+     ** I18N
+     */
+    if (nuxt.options.i18n && nuxt.options.i18n.locales) {
+      const { resolve } = createResolver(import.meta.url);
+
+      // Filter locales to only include existing ones
+      const filteredLocales = nuxt.options.i18n.locales.filter((locale) => {
+        const localeCode = typeof locale === "string" ? locale : locale.code;
+
+        // Check for JSON locale file
+        const localeFilePath = resolve("../i18n/locales", `${localeCode}.json`);
+        const hasLocaleFile = existsSync(localeFilePath);
+
+        // Check for content folder
+        const contentPath = join(nuxt.options.rootDir, "content", localeCode);
+        const hasContentFolder = existsSync(contentPath);
+
+        if (!hasLocaleFile) {
+          console.warn(
+            `[Docus] Locale file not found: ${localeCode}.json - skipping locale "${localeCode}"`,
+          );
+        }
+
+        if (!hasContentFolder) {
+          console.warn(
+            `[Docus] Content folder not found: content/${localeCode}/ - skipping locale "${localeCode}"`,
+          );
+        }
+
+        return hasLocaleFile && hasContentFolder;
+      });
+
+      // Override strategy to prefix
+      nuxt.options.i18n = {
+        ...nuxt.options.i18n,
+        strategy: "prefix",
+      };
+
+      // Expose filtered locales
+      nuxt.options.runtimeConfig.public.docus = {
+        filteredLocales,
+      };
+
+      nuxt.hook("i18n:registerModule", (register) => {
+        const langDir = resolve("../i18n/locales");
+
+        const locales = filteredLocales?.map((locale) => {
+          return typeof locale === "string"
+            ? {
+                code: locale,
+                name: locale,
+                file: `${locale}.json`,
+              }
+            : {
+                code: locale.code,
+                name: locale.name || locale.code,
+                file: `${locale.code}.json`,
+              };
+        });
+
+        register({
+          langDir,
+          locales,
+        });
+      });
+    }
+  },
+});

package/modules/routing.ts

@@ -0,0 +1,20 @@
+import { defineNuxtModule, createResolver } from "@nuxt/kit";
+
+export default defineNuxtModule({
+  meta: {
+    name: "routing",
+  },
+  async setup(_options, nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+
+    // Ensure useDocusI18n is available in the app
+    nuxt.hook("imports:extend", (imports) => {
+      if (imports.some((i) => i.name === "useDocusI18n")) return;
+
+      imports.push({
+        name: "useDocusI18n",
+        from: resolve("../app/composables/useDocusI18n"),
+      });
+    });
+  },
+});

package/nuxt.config.ts

@@ -0,0 +1,130 @@
+import { createResolver, useNuxt } from "@nuxt/kit";
+
+const { resolve } = createResolver(import.meta.url);
+
+/**
+ * `@uxfront/layer-docs` — a neutral, brandable Nuxt-layer documentation theme.
+ *
+ * Consumers extend it via `extends: ['@uxfront/layer-docs']` and supply their
+ * own branding (title, logos, socials, palette) through their `app.config.ts`,
+ * merged over the layer's neutral defaults by Nuxt's `defu` layer merge. The
+ * section topology (`DOCS_SECTIONS`) and markdown content stay in the consumer.
+ *
+ * i18n is OFF by default: `@nuxtjs/i18n` is not registered here, so a v1 single
+ * locale site "just works". A consumer that wants localisation registers the
+ * module itself; `modules/config` + `useDocusI18n` pick it up automatically.
+ *
+ * https://nuxt.com/docs/getting-started/layers
+ */
+export default defineNuxtConfig({
+  compatibilityDate: "2025-07-22",
+  telemetry: false,
+  css: [resolve("./app/assets/css/main.css")],
+  // Expose `app/constants/` (DOCS_SECTIONS, findDocsSectionBySlug) as
+  // auto-imports. The layer ships a neutral empty default; a consumer's own
+  // `app/constants/` overrides it via auto-import dir precedence.
+  imports: {
+    dirs: ["constants"],
+  },
+  modules: [
+    resolve("./modules/config"),
+    resolve("./modules/routing"),
+    "@nuxt/ui",
+    "@nuxt/image",
+    "@nuxt/scripts",
+    "@nuxtjs/robots",
+    "@nuxtjs/sitemap",
+    "@nuxt/content",
+    "nuxt-llms",
+  ],
+  icon: {
+    serverBundle: "local",
+    fetchTimeout: 10000,
+  },
+  // Syntax-highlighting language set + MDC auto-unwrap. Shared across every
+  // docs consumer; brand-agnostic.
+  content: {
+    build: {
+      markdown: {
+        highlight: {
+          langs: [
+            "bash",
+            "diff",
+            "json",
+            "js",
+            "ts",
+            "tsx",
+            "html",
+            "css",
+            "vue",
+            "svelte",
+            "astro",
+            "shell",
+            "mdc",
+            "md",
+            "yaml",
+          ],
+        },
+        remarkPlugins: {
+          "remark-mdc": {
+            options: {
+              autoUnwrap: true,
+            },
+          },
+        },
+      },
+    },
+  },
+  nitro: {
+    prerender: {
+      crawlLinks: true,
+      failOnError: false,
+      autoSubfolderIndex: false,
+    },
+  },
+  hooks: {
+    // Seed the prerender crawl with the site root(s). Without i18n that's just
+    // "/"; with i18n it's each locale root ("/en", "/fr", ...). Everything else
+    // is reached via crawlLinks.
+    "nitro:config"(nitroConfig) {
+      const nuxt = useNuxt();
+      const i18nOptions = nuxt.options.i18n as
+        | { locales?: Array<string | { code: string }> }
+        | undefined;
+
+      const routes: string[] = [];
+      if (!i18nOptions?.locales?.length) {
+        routes.push("/");
+      } else {
+        routes.push(
+          ...i18nOptions.locales.map((locale) =>
+            typeof locale === "string" ? `/${locale}` : `/${locale.code}`,
+          ),
+        );
+      }
+
+      nitroConfig.prerender = nitroConfig.prerender || {};
+      nitroConfig.prerender.routes = nitroConfig.prerender.routes || [];
+      nitroConfig.prerender.routes.push(...routes);
+    },
+  },
+  // Generic sitemap defaults; brand values (url/name) come from the consumer's
+  // `site` config or are inferred in `modules/config`.
+  sitemap: {
+    enabled: true,
+    discoverImages: true,
+    discoverVideos: true,
+  },
+  // Neutral analytics defaults. The PostHog client plugin (ships in this layer)
+  // only initialises in production when `app.config` `analytics.enabled` is true
+  // and a key is present; consumers override the key/host from their own env.
+  runtimeConfig: {
+    public: {
+      posthog: {
+        key: "",
+        host: "https://us.i.posthog.com",
+        defaults: "2025-05-24",
+      },
+    },
+  },
+});