@wordup-md/nuxt-layer-shadcn-unocss 0.2.0

package/.playground/content/4.development/1.configuration/1.overview.md

@@ -0,0 +1,297 @@
+---
+title: Overview
+description: Customizing shadcn-docs-nuxt.
+icon: lucide:settings-2
+---
+
+shadcn-docs-nuxt is configured through `app.config.ts`.
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  shadcnDocs: {
+    header: {
+      // ...
+    },
+    aside: {
+      // ...
+    },
+    main: {
+      // ...
+    },
+    // ...
+  },
+});
+```
+
+## Fields Reference
+
+Illustrative type declarations:
+
+```ts
+type Target = '_blank' | '_parent' | '_self' | '_top' | (string & object) | null | undefined;
+
+interface ILink {
+  title?: string;
+  icon?: string;
+  to: string;
+  target?: Target;
+  showLinkIcon?: boolean; // For nav and toc link section
+}
+
+interface INav {
+  title: string;
+  links?: (ILink & { description: string; icon: string })[];
+  to?: string;
+  target?: Target;
+}
+```
+
+### Icons
+
+All configurable icons can be set to iconify icons, emojis and urls, using the [icon component](/components/docs/icon) under the hood.
+
+## `site`
+
+::field-group
+  ::field{name="name" type="string"}
+  The site name shown on the tap title: `<page> - <site_name>`.
+  ::
+  ::field{name="description" type="string"}
+  The site description for SEO.
+  ::
+  ::field{name="ogImage" type="string"}
+  The path to the Open Graph image.
+  ::
+  ::field{name="ogImageComponent" type="string" default-value="ShadcnDocs"}
+  The component to use for the dynamic ogImage. Possible values: `ShadcnDocs`, `Nuxt`, `NuxtSeo` or your custom component name.
+  ::
+  ::field{name="ogImageColor" type="'light' | 'dark'" default-value="light"}
+  Color mode to use for the dynamic ogImage.
+  ::
+  ::field{name="umami" type="object"}
+    ::collapsible{title="Details"}
+      ::field-group
+        ::field{name="enable" type="boolean" default-value="false"}
+        Whether to turn on the umami integration.
+        ::
+        ::field{name="src" type="string" default-value="https://cloud.umami.is/script.js"}
+        The link src in the tracking code.
+        ::
+        ::field{name="dataWebsiteId" type="string"}
+        The _Website ID_ from umami dashboard.
+        ::
+      ::
+    ::
+  ::
+::
+
+## `theme`
+
+::field-group
+  ::field{name="customizable" type="boolean" defaultValue="true"}
+  Whether the theme can be customized by the user (show the customize button in the header).
+  ::
+  ::field{name="color" type="Color" defaultValue="zinc"}
+  The default color theme. https://www.shadcn-vue.com/themes.html
+  ::
+  ::field{name="radius" type="string" defaultValue="0.5"}
+  The default radius.
+  ::
+::
+
+## `banner`
+
+:read-more{to="/development/configuration/banner"}
+
+::field-group
+  ::field{name="enable" type="boolean" default-value="false"}
+  Whether to enable the banner.
+  ::
+  ::field{name="showClose" type="boolean" default-value="true"}
+  Whether to show to close button.
+  ::
+  ::field{name="to" type="string"}
+  Link to navigate to. Don't set any value if you don't want to navigate.
+  ::
+  ::field{name="content" type="string"}
+  The content to show (parsed by the MDC parser).
+  ::
+  ::field{name="target" type="Target" default-value="_blank"}
+  Navigation target.
+  ::
+  ::field{name="border" type="boolean" default-value="true"}
+  Whether to show the border at the bottom of the banner.
+  ::
+::
+
+## `header`
+
+::field-group
+  ::field{name="showLoadingIndicator" type="boolean" defaultValue="true"}
+  Whether to show the nuxt loading indicator.
+  ::
+  ::field{name="title" type="string"}
+  The title shown on the header next to the icon.
+  ::
+  ::field{name="showTitle" type="boolean" defaultValue="true"}
+  Whether to show the title text on the header.
+  ::
+  ::field{name="border" type="boolean" defaultValue="false"}
+  Whether to show the bottom border of the header.
+  ::
+  ::field{name="darkModeToggle" type="boolean" defaultValue="true"}
+  Whether to show the dark mode toggle.
+  ::
+  ::field{name="logo" type="{ light: string; dark: string; }" defaultValue="{ light: '/logo.svg', dark: '/logo-dark.svg' }"}
+  The path to the logo image files in `/public`. `light` is for the icon shown in light mode, `dark` is for the icon shown in dark mode.
+  ::
+  ::field{name="showTitleInMobile" type="boolean" defaultValue="false"}
+  Whether to show the logo and title in mobile. (Recommended to use with [button styled search bar](/development/configuration#search))
+  ::
+  ::field{name="nav" type="INav[]" defaultValue="[]"}
+  The content of the navbar in the header.
+  ::
+  ::field{name="links" type="ILink[]" defaultValue="[]"}
+  The links on the right of the header.
+  ::
+::
+
+## `aside`
+
+::field-group
+  ::field{name="useLevel" type="boolean" defaultValue="true"}
+  Whether to use level-styled sidebar.
+  ::
+  ::field{name="collapse" type="boolean" defaultValue="false"}
+  Whether to collapse all collapsible by default.
+  ::
+  ::field{name="collapseLevel" type="number" defaultValue="1"}
+  Collapse folders that are deeper than the defined level. (Set it to `Infinity` if you want to expand all)
+  ::
+  ::field{name="folderStyle" type="'default' | 'tree' | 'group'" defaultValue="default"}
+  The default style used for [folders](/getting-started/writing/folders#parameters).
+  ::
+::
+
+## `main`
+
+::field-group
+  ::field{name="padded" type="boolean" defaultValue="true"}
+  Whether the page is padded.
+  ::
+  ::field{name="breadCrumb" type="boolean" defaultValue="true"}
+  Whether to show the bread crumb.
+  ::
+  ::field{name="showTitle" type="boolean" defaultValue="true"}
+  Whether to show the title section.
+  ::
+  ::field{name="codeCopyToast" type="boolean" defaultValue="true"}
+  Whether to show a toast on code copy.
+  ::
+  ::field{name="codeCopyToastText" type="string" defaultValue="'Copied to clipboard!'"}
+  The text shown in the toaster.
+  ::
+  ::field{name="fieldRequiredText" type="string" defaultValue="'required'"}
+  The text shown in the [field](/components/docs/field) component when a field is required.
+  ::
+  ::field{name="pm" type="('npm' | 'pnpm' | 'bun' | 'yarn')[]" default-value="['npm', 'pnpm', 'bun', 'yarn']"}
+  Package managers shown in the [pm components](/components/docs/pm).
+  ::
+  ::field{name="codeIcon" type="Record<string, string>"}
+  The icon mapping for language / filename in the [code group](/components/docs/code-group) header.
+  ::
+  ::field{name="editLink" type="object"}
+    ::collapsible{title="Details"}
+      ::field-group
+        ::field{name="enable" type="boolean" default-value="false"}
+        Whether to turn on the edit link.
+        ::
+        ::field{name="pattern" type="string"}
+        The link pattern.
+        ::
+        ::field{name="text" type="string" default-value="Edit this page"}
+        Text displayed on the link.
+        ::
+        ::field{name="icon" type="string" default-value="lucide:square-pen"}
+        The icon preceding the link.
+        ::
+        ::field{name="placement" type="('docsFooter' | 'toc')[]" default-value="['docsFooter']"}
+        Where to place the edit link.
+        ::
+      ::
+    ::
+  ::
+::
+
+## `footer`
+
+::field-group
+  ::field{name="credits" type="string" defaultValue="''"}
+  The credit text on the left side of the footer (parsed by the MDC parser).
+  ::
+  ::field{name="links" type="ILink[]" defaultValue="[]"}
+  The links on the right side of the footer.
+  ::
+::
+
+## `toc`
+
+::field-group
+  ::field{name="enable" type="boolean" defaultValue="true"}
+  Whether to turn on the toc section.
+  ::
+  ::field{name="enableInMobile" type="boolean" defaultValue="false"}
+  Whether to turn on the toc section in mobile.
+  ::
+  ::field{name="title" type="string" defaultValue="'On This Page'"}
+  The title for the toc section.
+  ::
+  ::field{name="links" type="ILink[]" defaultValue="[]"}
+  The links under the toc section.
+  ::
+  ::field{name="carbonAds" type="object"}
+    ::collapsible{title="Details"}
+      ::field-group
+        ::field{name="enable" type="boolean" default-value="false"}
+        Whether to turn on Carbon Ads.
+        ::
+        ::field{name="disableInDev" type="boolean" default-value="false"}
+        Whether to disable Carbon Ads in dev environment.
+        ::
+        ::field{name="code" type="string"}
+        Carbon Ads code.
+        ::
+        ::field{name="placement" type="string"}
+        Carbon Ads placement.
+        ::
+        ::field{name="format" type="'cover' | 'responsive'" default-value="cover"}
+        Carbon Ads format.
+        ::
+      ::
+    ::
+  ::
+::
+
+## `search`
+
+::field-group
+  ::field{name="enable" type="boolean" defaultValue="true"}
+  Whether to turn on the search feature.
+  ::
+  ::field{name="inAside" type="boolean" defaultValue="false"}
+  Whether to show the search bar in the sidebar.
+  ::
+  ::field{name="style" type="'input' | 'button'" defaultValue="input"}
+  Whether the search bar is displayed as a input or a button.
+  ::
+  ::field{name="placeholder" type="string" defaultValue="'Search...'"}
+  The placeholder text shown in the search bar.
+  ::
+  ::field{name="placeholderDetailed" type="string" defaultValue="'Search documentation...'"}
+  The placeholder text shown in the search dialog input.
+  ::
+::
+
+## Default Config
+
+:read-more{to="https://github.com/ZTL-UwU/shadcn-docs-nuxt/blob/main/composables/useConfig.ts" title="source file" icon="lucide:code"}

package/.playground/content/4.development/1.configuration/2.nuxt-content.md

@@ -0,0 +1,105 @@
+---
+title: Nuxt Content
+description: Configuring the Nuxt Content module.
+icon: lucide:book
+---
+
+::Alert
+---
+to: https://content.nuxt.com/get-started/configuration
+target: _blank
+---
+Read the detailed configuration guide in **Nuxt Content** Docs.
+::
+
+The default nuxt content config can be overridden in `nuxt.config.ts`.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  devtools: { enabled: true },
+  extends: ['shadcn-docs-nuxt'],
+
+  // Here
+  content: {
+    // ...
+  },
+
+  compatibilityDate: '2024-07-06',
+});
+```
+
+## Syntax Highlighting
+
+### Theme
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  content: {
+    highlight: {
+      theme: {
+        // Default theme
+        default: 'github-light',
+        // Theme used in dark-mode
+        dark: 'github-dark',
+      }
+    }
+  }
+});
+```
+
+:read-more{to="https://shiki.style/themes"}
+
+### Languages
+
+The default highlighted languages are: `['json', 'js', 'ts', 'html', 'css', 'vue', 'diff', 'shell', 'markdown', 'yaml', 'bash', 'ini']`{lang="js"}.
+
+If you need to highlight other languages, add them in your `nuxt.config.ts`.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  content: {
+    highlight: {
+      langs: ['c', 'cpp'],
+    },
+  },
+});
+```
+
+:read-more{to="https://shiki.style/languages"}
+
+## Default Config
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  content: {
+    documentDriven: true,
+    highlight: {
+      theme: {
+        default: 'github-light',
+        dark: 'github-dark',
+      },
+      preload: ['json', 'js', 'ts', 'html', 'css', 'vue', 'diff', 'shell', 'markdown', 'yaml', 'bash', 'ini'],
+    },
+    navigation: {
+      fields: [
+        'description',
+        'icon',
+        'navBadges',
+        'navTruncate',
+        'badges',
+        'toc',
+        'sidebar',
+        'collapse',
+        'editLink',
+        'prevNext',
+        'breadcrumb',
+      ],
+    },
+    experimental: {
+      search: {
+        indexed: true,
+      },
+    },
+  },
+});
+```

package/.playground/content/4.development/1.configuration/3.og-image.md

@@ -0,0 +1,86 @@
+---
+title: OG Image
+description: Customizing the dynamic OG Image.
+icon: lucide:image
+---
+
+**shadcn-docs-nuxt** utilizes the [nuxt-og-image](https://nuxtseo.com/og-image/getting-started/installation) module to generate dynamic OG Images.
+
+The dynamic OG Image is used in all pages **except** the index page. The index page uses a static OG Image defined in the [`ogImage`](/development/configuration/overview#site) field instead.
+
+## Using Built-in Templates
+
+To use a template, set the name of the OG Image component in the [`ogImageComponent`](/development/configuration/overview#site).
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  shadcnDocs: {
+    site: {
+      ogImageComponent: 'ShadcnDocs',
+      ogImageColor: 'light', // or 'dark'
+    },
+  },
+});
+```
+
+Out of the box, a shadcn-docs-nuxt template and multiple community templates are available.
+
+::tabs{variant="card"}
+  ::div{label="ShadcnDocs"}
+    ![Shadcn Docs OG Image Preview](/og-shadcn-docs.png){width="1000"}
+  ::
+  ::div{label="ShadcnDocs (Dark)"}
+    ![Shadcn Docs OG Image Preview](/og-shadcn-docs-dark.png){width="1000"}
+  ::
+  ::div{label="Nuxt"}
+    ![Nuxt OG Image Preview](/og-nuxt.png){width="1000"}
+  ::
+  ::div{label="Nuxt SEO"}
+    ![NuxtSEO OG Image Preview](/og-nuxt-seo.png){width="1000"}
+  ::
+::
+
+::alert{to="https://github.com/nuxt-modules/og-image/tree/main/src/runtime/nuxt/components/Templates/Community" icon="lucide:list"}
+See the full list of community templates.
+::
+
+## Using Custom Templates
+
+To use a custom template, create a template by following the guide in the [Nuxt SEO Docs](https://nuxtseo.com/og-image/getting-started/getting-familar-with-nuxt-og-image#_1-create-your-template-component). Then set the component name of your template in `ogImageComponent`.
+
+::code-group
+```vue [components/OgImage/BlogPost.vue]
+<template>
+  <div class="flex size-full items-start justify-start border-[12px] border-solid border-blue-500 bg-gray-50">
+    <div class="flex h-full items-start justify-start">
+      <div class="flex size-full flex-col justify-between">
+        <h1 class="p-20 text-left text-[80px] font-black">
+          {{ title }}
+        </h1>
+        <p class="mb-0 px-20 pb-10 text-2xl font-bold">
+          mycoolsite.com
+        </p>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+withDefaults(defineProps<{
+  title?: string;
+}>(), {
+  title: 'title',
+});
+</script>
+```
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  shadcnDocs: {
+    site: {
+      ogImageComponent: 'BlogPost',
+    },
+  },
+});
+```
+::

package/.playground/content/4.development/1.configuration/4.edit-link.md

@@ -0,0 +1,63 @@
+---
+title: Edit Link
+icon: lucide:square-pen
+description: A link to the source file.
+---
+
+An edit link allows you to display a link at the end of each page to edit the page on GitHub / GitLab.
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  shadcnDocs: {
+    main: {
+      editLink: {
+        enable: true,
+        pattern: 'https://github.com/ZTL-UwU/shadcn-docs-nuxt/edit/main/content/:path',
+        text: 'Edit this page on GitHub',
+        icon: 'lucide:square-pen',
+        placement: ['docsFooter', 'toc'],
+      },
+    }
+  },
+});
+```
+
+- The `pattern` option defines the URL structure for the link, and `:path` is going to be replaced with the page path.
+
+- The `text` option allows you to customize the link text (default is `Edit this page`)
+
+- The `icon` option allows you to customize the icon (default is `lucide:square-pen`)
+
+- The `placement` option controls the places to put the edit link.
+  - `docsFooter`: at the end of the page.
+  - `toc`: in the TOC links section.
+
+### Front Matter
+
+The edit link can be disabled per-page using the `editLink` option in front matter.
+
+```yaml
+---
+editLink: false
+---
+```
+
+## Parameters
+
+::field-group
+  ::field{name="enable" type="boolean" default-value="false"}
+  Whether to turn on the edit link.
+  ::
+  ::field{name="pattern" type="string"}
+  The link pattern.
+  ::
+  ::field{name="text" type="string" default-value="Edit this page"}
+  Text displayed on the link.
+  ::
+  ::field{name="icon" type="string" default-value="lucide:square-pen"}
+  The icon preceding the link.
+  ::
+  ::field{name="placement" type="('docsFooter' | 'toc')[]" default-value="['docsFooter']"}
+  Where to place the edit link.
+  ::
+::

package/.playground/content/4.development/1.configuration/5.banner.md

@@ -0,0 +1,52 @@
+---
+title: Banner
+icon: lucide:panel-top
+description: Show a banner on the top of the page.
+badges:
+  - value: Source
+    icon: lucide:code
+    to: https://github.com/ZTL-UwU/shadcn-docs-nuxt/blob/main/components/layout/Banner.vue
+    target: _blank
+  - value: 0.8.3
+---
+
+::stack
+```ts [app.config.ts]
+export default defineAppConfig({
+  shadcnDocs: {
+    banner: {
+      enable: true,
+      showClose: true,
+      content: 'Welcome to **shadcn-docs-nuxt**',
+      to: 'https://github.com/ZTL-UwU/shadcn-docs-nuxt',
+      target: '_blank',
+      border: true,
+    },
+  },
+});
+```
+![Preview](/banner-preview.png){width="1000"}
+::
+
+## Parameters
+
+::field-group
+  ::field{name="enable" type="boolean" default-value="false"}
+  Whether to enable the banner.
+  ::
+  ::field{name="showClose" type="boolean" default-value="true"}
+  Whether to show to close button.
+  ::
+  ::field{name="to" type="string"}
+  Link to navigate to. Don't set any value if you don't want to navigate.
+  ::
+  ::field{name="content" type="string"}
+  The content to show (parsed by the MDC parser).
+  ::
+  ::field{name="target" type="Target" default-value="_blank"}
+  Navigation target.
+  ::
+  ::field{name="border" type="boolean" default-value="true"}
+  Whether to show the border at the bottom of the banner.
+  ::
+::

package/.playground/content/4.development/1.configuration/6.carbon-ads.md

@@ -0,0 +1,65 @@
+---
+title: Carbon Ads
+icon: lucide:chart-line
+description: Run ads at the bottom of the TOC section.
+---
+
+**shadcn-docs-nuxt** has built-in support for [Carbon Ads](https://www.carbonads.net/). Add your Carbon Ads credentials to `app.config.ts` and ads will be displayed at the bottom of the toc section.
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  shadcnDocs: {
+    toc: {
+      enable: true,
+      carbonAds: {
+        enable: true,
+        disableInDev: false,
+        code: 'your-carbon-code',
+        placement: 'your-carbon-placement',
+        format: 'your-carbon-format', // defaults to 'cover'
+      },
+    }
+  },
+});
+```
+
+These values are used to call carbon CDN script as shown below.
+
+```ts
+`//cdn.carbonads.com/carbon.js?serve=${code}&placement=${placement}&format=${format}`;
+```
+
+:read-more{title="Carbon Ads website" to="https://www.carbonads.net/"}
+
+### Disabling on certain pages
+
+```md
+---
+title: Page Title
+toc:
+  carbonAds:
+    enable: false
+---
+
+<!-- Page Content -->
+```
+
+## Parameters
+
+::field-group
+  ::field{name="enable" type="boolean" default-value="false"}
+  Whether to turn on Carbon Ads.
+  ::
+  ::field{name="disableInDev" type="boolean" default-value="false"}
+  Whether to disable Carbon Ads in dev environment.
+  ::
+  ::field{name="code" type="string"}
+  Carbon Ads code.
+  ::
+  ::field{name="placement" type="string"}
+  Carbon Ads placement.
+  ::
+  ::field{name="format" type="'cover' | 'responsive'" default-value="cover"}
+  Carbon Ads format.
+  ::
+::