Configuration

Docus allows you to configure your documentation through the app.config.ts file provided by Nuxt.

SEO

Technical SEO is tricky and boring. Docus offers a solid, opt-in default setup that works out of the box, while giving you full control to customize your SEO metadata, from page titles to social sharing images.

Metadata

Docus offers flexible SEO metadata configuration, allowing you to easily override values globally or on a per-page basis.

Global configuration

Define default SEO metas for your entire documentation in app.config.ts. These values will be used as fallbacks across pages that don’t specify their own in the front-matter as described in next section.

You can also configure your site.name value from your nuxt.config.ts file, default is based on your package.json name.

export default defineAppConfig({
  seo: {
    // Default to `%s - ${site.name}`
    titleTemplate: ''
    // Default to package.json name
    title: '',
    // Default to package.json description
    description: ''
  },
})

export default defineNuxtConfig({
  site: {
    name: 'Docus',
  },
})

Per-page configuration

Each Markdown file in the content/ directory starts with a frontmatter block (---). You can define SEO metadata per page by using the seo key:

---
seo:
  title: 'Configuration'
  description: 'Customize your Docus documentation from the Nuxt application configuration file.'
---

<!-- Page content -->

Social sharing (OG) image

When you share a link of your documentation on social media or some chat platforms, the link will be unfurled, in other terms it gives a glimpse of what someone linked (displaying a title, description, and an image). All of these are powered by the Open Graph Protocol.

Documentation pages

We're using Nuxt OG Image under the hood to generate OG image for each documentation page based on the provided title and description. For example, the OG image for the current page is:

Landing page

Same as the documentation pages, the landing page uses the same OG image generator based on the provided title and description.

However, if you want to customize the OG image for your landing page, you can do so by adding a absolute path to an image in the the seo.ogImage key of your frontmatter.

---
seo:
  ogImage: '/social-card.png'
---

We recommend using a 1280×640 image for optimal display on social platforms.

Header

Configure your documentation site’s title or logo :

export default defineAppConfig({
  header: {
    // Title to display if no logo
    title: '',
    // Logo configuration
    logo: {
      alt: '',
      // Light mode
      light: '',
      // Dark mode
      dark: ''
    },
  },
})

Socials Links

Add your social media links in the footer using a Record<string, string> where the key matches an icon from Simple Icons library.

export default defineAppConfig({
  socials: {
    x: 'https://x.com/nuxt_js',
    discord: 'https://discord.com/invite/ps2h6QT',
    nuxt: 'https://nuxt.com',
  }
})

Table of Contents

You can customize the table of content on the right sidebar of each page.

export default defineAppConfig({
  toc: {
    // Rename the title of the table of contents
    title: 'On this page',
    // Add a bottom section to the table of contents
    bottom: {
      title: 'Community',
      links: [{
        icon: 'i-lucide-book-open',
        label: 'Nuxt UI Pro docs',
        to: 'https://ui.nuxt.com/getting-started/installation/pro/nuxt',
        target: '_blank'
      }, {
        icon: 'i-simple-icons-nuxtdotjs',
        label: 'Purchase a license',
        to: 'https://ui.nuxt.com/pro/purchase',
        target: '_blank'
      }]
    }
  }
})

GitHub Integration

Docus reads your .git/ folder to get the url and branch of your repository to add:

• GitHub icon in the header and footer
• Edit this page and Report an issue links in the footer of each page.

You can customize the url and branch by adding the following configuration to your app.config.ts file:

export default defineAppConfig({
  github: {
    url: 'https://github.com/nuxt-ui-pro/docuss',
    branch: 'main'
  }
})

If you don't want to use GitHub, you can set the github key to false to disable the GitHub integration.

export default defineAppConfig({
  github: false
})