first commit

docs/content/2.concepts/3.configuration.md

@@ -0,0 +1,191 @@
+---
+title: Configuration
+navigation:
+  icon: i-lucide-settings
+description: "Customize your Docus documentation from the Nuxt application
+  configuration file. "
+seo:
+  description: Customize your Docus documentation from Nuxt application configuration file.
+---
+
+Docus allows you to configure your documentation through the [app.config.ts](https://nuxt.com/docs/guide/directory-structure/app-config) 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.
+
+::prose-code-group
+```ts [app.config.ts]
+export default defineAppConfig({
+  seo: {
+    // Default to `%s - ${site.name}`
+    titleTemplate: ''
+    // Default to package.json name
+    title: '',
+    // Default to package.json description
+    description: ''
+  },
+})
+```
+
+```ts [nuxt.config.ts]
+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:
+
+```md [content/concepts/configuration.md]
+---
+seo:
+  title: 'Configuration'
+  description: 'Customize your Docus documentation from the Nuxt application configuration file.'
+---
+
+<!-- Page content -->
+```
+
+::prose-tip{to="/concepts/edition#frontmatter"}
+For more details on front-matter, see the edition guide.
+::
+
+### **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](https://nuxtseo.com/docs/og-image/getting-started/introduction) 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:
+
+![og image documentation page](https://docus.dev/__og-image__/static/concepts/configuration/og.png){.rounded-lg}
+
+#### Landing page
+
+Same as the documentation pages, the landing page uses the same OG image generator based on the provided title and description.
+
+![og image landing page](https://docus.dev/__og-image__/static/og.png){.rounded-lg}
+
+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.
+
+```md [content/index.md]
+---
+seo:
+  ogImage: '/social-card.png'
+---
+```
+
+We recommend using a **1280×640** image for optimal display on social platforms.
+
+::prose-tip
+OG images must be served with absolute URLs. By default, the site URL is inferred from your deployment platform, but you can override it by setting the `NUXT_SITE_URL` environment variable.
+::
+
+## Header
+
+Configure your documentation site’s `title` or `logo` :
+
+```ts [app.config.ts]
+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](https://simpleicons.org/) library.
+
+```ts [app.config.ts]
+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.
+
+```ts [app.config.ts]
+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`, `branch` and `rootDir` of your docs application by adding the following configuration to your `app.config.ts` file:
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  github: {
+    url: 'https://github.com/nuxt-ui-pro/docus',
+    branch: 'main',
+    rootDir: 'docs'
+  }
+})
+```
+
+If you don't want to use GitHub, you can set the `github` key to `false` to disable the GitHub integration.
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  github: false
+})
+```
+
+::prose-tip{to="/getting-started/studio"}
+Those configurations can also be handled in Studio editor, give it a try!
+::