@sit-onyx/nuxt-docs

Nuxt layer/template for creating documentations with the onyx design system. You can easily write markdown files and they will be rendered with pre-defined layouts and onyx components. Fully flexible and customizable.

Nuxt layer/template for creating documentations with the onyx design system.

Work in progress

This package is work in progress. More features will be added in the future.

Changelog

A full changelog can be found here.

Features

The package includes the following features:

• pre-defined page layouts (landing page, docs etc.)
• pre-configured Nuxt content module to render markdown pages with onyx components.
• custom user friendly error page for 404, unexpected errors etc.
• supports Nuxt 4
• integration with Nuxt i18n

Installation

Step 1: Create a basic Nuxt project

To get started, you need a basic Nuxt project. You can check out the Nuxt documentation for this.

app.vue

Important! If your Nuxt project has a app/app.vue file, delete it. Otherwise the whole documentation template will be overridden and not work correctly.

Step 2: Configure pnpm

If you are using pnpm, make sure to create the following pnpm-workspace-yaml and .npmrc file. Otherwise the Nuxt layer will not work correctly. When using another package manager, you can skip this step.

pnpm-workspace.yaml

# needed to correctly install the Nuxt content and Nuxt image module
onlyBuiltDependencies:
  - better-sqlite3
  - sharp

.npmrc

# "shamefully-hoist" is the default config from Nuxt for layers
# It is currently needed to correctly install the peerDependencies from Nuxt layers
shamefully-hoist=true

Step 3: Install the onyx documentation template

Install the onyx documentation layer by running

pnpm

pnpm add @sit-onyx/nuxt-docs@beta

npm

npm install @sit-onyx/nuxt-docs@beta

yarn

yarn install @sit-onyx/nuxt-docs@beta

Step 4: Enable the Nuxt layer

Now, just extend your application with the onyx layer. You can check the Nuxt documentation for further information.

nuxt.config.ts

export default defineNuxtConfig({
  extends: ["@sit-onyx/nuxt-docs"],
});

Done! You can now start to write markdown files and see the renderer output in your application.

Step 5: Create your first page

Finally create your first content page by creating a content/en/index.md file which will be the home/landing page of your documentation. For more information about writing markdown/content, see the Write markdown section.

content/en/index.md

# Hello World

This is an example page using the [onyx documentation template](https://onyx.schwarz/development/packages/nuxt-docs.html) for Nuxt.

INFO

By default, the content/en folder is used to provide the content so all files must be placed inside this folder. If you want to add other languages or change the default language, refer to thr i18n section.

Customization

Due to the nature of Nuxt layers, almost every part of the default config and components can be overridden or customized if needed.

Layer exports

All components, pages, composables etc. from the @sit-onyx/nuxt-docs layer can be imported from #layers/onyx/*. This is especially useful when customizing existing components (see example below).

To override or customize a component provided by @sit-onyx/nuxt-docs, you first need to create new component in your project with the same name as the one that you want to customize. In this example, we will add nav items to the default nav bar.

By default, Nuxt will prioritize project-specific components over the ones provided by Nuxt layers (thats what @sit-onyx/nuxt-docs is) so in this example, the default nav bar would be replaced completely.

While this can be useful for certain use cases, in this example we only want to extend / customize the default nav bar instead of replacing it completely so we can still benefit from the default nav bar features. Therefore, we will import the default nav bar from #layers/onyx and use its supported slots to add nav items. You could also e.g. change props at this point.

app/components/NavBar.vue

<script lang="ts" setup>
import NavBar from "#layers/onyx/app/components/NavBar.vue";

// localePath from Nuxt i18n is used here to ensure correct links depending on the current locale and i18n routing strategy
// e.g. for a "de" locale, the paths might be prefixed with "/de"
const localePath = useLocalePath();
</script>

<template>
  <NavBar>
    <OnyxNavItem label="Home" :link="localePath('/')" />
    <OnyxNavItem label="Foo" :link="localePath('/foo')" />
    <OnyxNavItem label="Does not exist" :link="localePath('/does-not-exist')" />
  </NavBar>
</template>

Thats it! The application will now show the nav items that we just passed while keeping all the default features from the nav bar like language and dark/light mode switch.

Write markdown

This documentation layer uses the official Nuxt content module. So to create pages/content with markdown, simply create a file inside the content folder of your application.

content/en/hello-world.md

# Hello World

This is an example page using the [onyx documentation template](https://onyx.schwarz/development/packages/nuxt-docs.html) for Nuxt.

Nuxt content will automatically create a route for every markdown file. In this example, the page will be available on /hello-world.

I18n

The Nuxt documentation template is integrated with Nuxt i18n so you can easily provide content in multiple languages.

When using multiple languages, the nav bar will automatically show a language switch where the user can switch the current language.

By default, en is used as default locale so you need to place all markdown files inside the content/en folder so they are picked up correctly. If you only plan to use English, you don't need to do anything and are good to go.

For further information about the Nuxt i18n integration with the Nuxt content module, read the official Nuxt content documentation.

Add language

To add other languages, follow the steps below.

Step 1: Add locale to Nuxt config

First, register all your desired locales in the nuxt.config.ts file so the Nuxt i18n module is aware of them.

nuxt.config.ts

export default defineNuxtConfig({
  i18n: {
    locales: [
      // make sure to also add the language property
      { code: "en", language: "en-US", name: "English" },
      { code: "de", language: "de-DE", name: "Deutsch" },
    ],
  },
});

Step 2: Configure Nuxt content module

Now you need to configure the Nuxt content module so it knows where to find the files / content for your languages.

content.config.ts

import { defineCollection, defineContentConfig } from "@nuxt/content";

export default defineContentConfig({
  collections: {
    // content_en is registered by default in @sit-onyx/nuxt-docs so there is no need to register it manually here
    // define a new collection for every additional language here
    content_de: defineCollection({
      type: "page",
      source: { include: "de/**", prefix: "" },
    }),
  },
});

You can now place content in the content/de folder to serve German content.

Change default locale

If you want to change the default locale to something other than English (e.g. if you don't want to offer English content), follow the steps below.

Step 1: Add default locale

Follow the same steps as described in the Add language section to register your new language.

Step 2: Change default locale

To change the default locale used by Nuxt i18n, just update the nuxt.config.ts accordingly (see Nuxt i18n docs for further information).

nuxt.config.ts

export default defineNuxtConfig({
  i18n: {
    defaultLocale: "de",
  },
});

Layouts

This documentation layer supports several pre-build layouts that are used by default. You can change the layout per page or add your own layouts if the existing ones do not fit your needs.

Coming soon

This package is work in progress. More features will be added in the future.

Components

There are also several components included in the documentation layer that you can optionally use to easily build e.g. team pages.

Coming soon

This package is work in progress. More features will be added in the future.