Documentation

Nuxt Docs

Copy link to headline:@sit-onyx/nuxt-docs

npm package
(opens in a new tab)

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.

.

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

Copy link to headline:Changelog

A full changelog can be found here.

Copy link to headline:Features

The package includes the following features:

Copy link to headline:Installation

Copy link to headline:Step 1: Create a basic Nuxt project

To get started, you need a basic Nuxt project. You can check out the Nuxt documentation(opens in a new tab) for this.

warning 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.

Copy link to headline: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.

Copy link to headline:Step 3: Install the onyx documentation template

Install the onyx documentation layer by running

Copy link to headline:Step 4: Enable the Nuxt layer

Now, just extend your application with the onyx layer. You can check the Nuxt documentation(opens in a new tab) for further information.

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

Copy link to headline: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.

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.

Copy link to headline:Customization

Due to the nature of Nuxt layers(opens in a new tab), almost every part of the default config and components can be overridden or customized if needed.

tip 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.

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.

Copy link to headline:Write markdown

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

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

Copy link to headline:I18n

The Nuxt documentation template is integrated with Nuxt i18n(opens in a new tab) 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(opens in a new tab).

Copy link to headline:Add language

To add other languages, follow the steps below.

Copy link to headline: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.

Copy link to headline:Step 2: Configure Nuxt content module

Now you need to configure the Nuxt content(opens in a new tab) module so it knows where to find the files / content for your languages.

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

Copy link to headline: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.

Copy link to headline:Step 1: Add default locale

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

Copy link to headline: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(opens in a new tab) for further information).

Copy link to headline:Layouts

This documentation layer supports several pre-build layouts(opens in a new tab) 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.

Copy link to headline:Default layout

Plain / blank OnyxPageLayout(opens in a new tab). Can be used to build fully custom pages.

Copy link to headline:Sidebar layout

Used as default for rendering markdown / content pages. Will automatically generate a sidebar with (nested) nav items, depending on your content structure.

The sidebar layout can be customized on folder-level by creating a .navigation.yml inside the corresponding folder. This allows to e.g. set the initial accordion collapsed state or define multiple roots so you can have multiple sections in your application where each section have their own sidebar hierarchy.

Copy link to headline:Components

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

Copy link to headline:NpmInstallCodeTabs

The NpmInstallCodeTabs can be used to display a command for installing one or multiple npm packages with common package managers (pnpm, npm, yarn or bun).