@uxfront/layer-docs

@uxfront/layer-docs

The Nuxt layer for UXFront's documentation sites. It extends Docus, which renders the markdown in content/docs/ with a header, sidebar, search and table of contents, and adds a framework switcher: every reader picks their framework once, and sees its examples on every page. It can also set the header's site name the way the UXFront homepages do, signed "by UXFront".

Install

pnpm add @uxfront/layer-docs

// nuxt.config.ts
export default defineNuxtConfig({
  extends: ["@uxfront/layer-docs"],
});

Then list the frameworks the docs' examples come in, in display order. The first is the default:

// app/app.config.ts
export default defineAppConfig({
  docsTheme: {
    frameworks: [
      { value: "react", label: "React", icon: "i-simple-icons-react" },
      { value: "vue", label: "Vue", icon: "i-simple-icons-vuedotjs" },
      { value: "svelte", label: "Svelte", icon: "i-simple-icons-svelte" },
    ],
  },
});

value is the slot name pages write each framework's examples in, and icon any Iconify icon. The layer ships no default list, so with none, the switcher and the select render nothing.

The header wordmark

Docus prints the site name in the header as plain text. Set docsTheme.wordmark to write it the way the UXFront homepages do, one part bold, and docsTheme.byline to sign it "by UXFront", linked to uxfront.com:

// app/app.config.ts
export default defineAppConfig({
  docsTheme: {
    // **Open**Components
    wordmark: { bold: "Open", regular: "Components" },
    byline: true,
  },
});

The wordmark links home, and its accessible name is Docus's header.title, or the site name. The byline sits beside the link, not inside it, and phones leave it out so the header's buttons keep their room. With neither set, the header shows Docus's own title or logo.

Writing examples

Put one slot per framework in a ::framework-switcher:

::framework-switcher
#react

```tsx [Button.tsx]
export const Button = () => <button>Save</button>;
```

#vue

```vue [Button.vue]
<template><button>Save</button></template>
```

::

It shows the code for the reader's framework. Docus only highlights a few languages (Vue, TypeScript, HTML, CSS, …), so the layer adds tsx, svelte, angular-html, angular-ts and astro. Add any other your examples need in the app's nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  content: {
    build: {
      markdown: {
        highlight: { langs: ["jsx"] },
      },
    },
  },
});

What it adds

• A Framework select above the sidebar. It picks the framework for the whole site, and lines up with the navigation's pages below it. It replaces Docus's DocsAsideLeftTop and renders Docus's below it.
• The same select in the header's menu. On smaller screens, where Docus hides the sidebar, the menu that stands in for it starts with the select. It replaces Docus's AppHeaderBody and renders Docus's below it.
• FrameworkSwitcher. It shows the slot for the reader's framework, with no tabs of its own, since the select already picks one for every page. A page doesn't have to cover every framework: a missing one shows the first one the page has, with a note saying so.
• A header wordmark and byline. It replaces Docus's AppHeaderLeft, and renders Docus's unless the app sets a wordmark.
• useFramework(). The reader's pick, shared by every switcher and the select, and kept in localStorage across visits. It's read once the page is mounted, so the prerendered HTML shows the default framework and hydrates cleanly.
• Highlighting for the frameworks' languages. tsx, svelte, angular-html, angular-ts and astro, on top of Docus's.
• Bundled icons. Nuxt Icon bundles the icons named in app config too, so the select's icons don't come from the Iconify API.

Everything else is Docus's: configure it as its docs describe.