Pages & Layouts

Besides docs pages, the layer generates the landing page, a releases page and a showcase page from files in the content directory, and you can write any Vue page in app/pages. This page covers when each built-in route is generated and its content format, header and footer switches for custom pages, and the built-in layouts.
View source

Built-in routes

RouteGenerated whenContent source
/The project has no app/pages/index.vuecontent/index.md
/docs/**Alwayscontent/docs/**
/releases, /releases/:tagcontent/releases.yml or content/releases.md existsGitHub Releases
/templatescontent/templates.yml or content/templates.md existsitems in the file

With i18n enabled, other locales put the matching files under content/{locale}/ (such as content/en/releases.yml); a locale without the file returns 404 for that route. Routes are decided at build time from the files present, so restart the dev server after adding or removing these files.

Landing page

Without app/pages/index.vue, the landing page renders content/index.md, where you can compose Nuxt UI page components with MDC:

content/index.md
---
title: My Docs
description: One sentence about your project.
---

::u-page-hero
#title
My Docs

#description
One sentence about your project.

#links
  :::u-button{to="/docs/getting-started" size="xl" trailing-icon="i-lucide-arrow-right"}
  Get started
  :::
::

To control the landing page entirely in code, create app/pages/index.vue. The layer then no longer injects the landing route or registers the landing content collection.

Releases page

/releases shows the latest release and paths such as /releases/v3.0.0 show a specific one. Data comes from the GitHub Releases of the repository set by github.owner / github.name in app.config:

  • The left column lists releases grouped by major version, the right column is the table of contents of the notes, and the bottom links to adjacent releases
  • Pages are server-rendered, so they can be prerendered and indexed; @username mentions in the notes link to GitHub profiles
  • When the releases page exists, version numbers in CommitChangelog link to the matching release on your site
Releases page
content/releases.yml
title: Releases
description: Release notes, new features and fixes of My Docs.
navigation: false
# Optional: list prereleases in the release navigation, defaults to false
prerelease: false
# Optional: only list releases whose tag matches this regular expression
include: '^v3\.'
GitHub data is cached on the server for one hour. In production, set NUXT_GITHUB_TOKEN to avoid the rate limits of anonymous requests; when GitHub is unreachable the page shows a notice instead of failing the build. Releases filtered out by prerelease or include are hidden from the navigation but remain reachable by their tag path.

Showcase page

/templates shows templates or real sites built with the theme as cards:

Showcase page
content/templates.yml
title: Showcase
description: Sites built with the My Docs theme.
navigation: false
hero:
  title: Showcase
  description: Sites built with the My Docs theme.
items:
  - title: '@my/core'
    description: Docs for a Vue utility library.
    features:
      - title: API reference
        icon: i-lucide-book-open
      - title: Component examples
        icon: i-lucide-shapes
    links:
      - label: Visit site
        to: https://core.example.com
        target: _blank
        icon: i-lucide-link
FieldDescription
heroTitle area at the top of the page, optionally with links buttons
items[].titleCard title, also used to derive the screenshot file name
items[].descriptionCard description
items[].featuresFeature list with icons
items[].linksButtons at the bottom of the card, with the same fields as Nuxt UI's UButton

Each card loads its screenshots from public/assets/templates/ by convention: {slug}-light.png and {slug}-dark.png. The slug is the lowercased title with runs of non-alphanumeric characters replaced by - and leading or trailing - removed, so @my/core maps to my-core-light.png and my-core-dark.png.

Neither page appears in the header automatically; add links in header.nav, see Navigation & Categories.

Custom pages

Add a Vue file to app/pages/ to create a page, following the usual Nuxt routing rules:

app/pages/showcase.vue
<script setup lang="ts">
definePageMeta({
  // Do not render the global header and footer
  header: false,
  footer: false
})

useSeoMeta({
  title: 'Showcase',
  description: 'A custom page example'
})
</script>

<template>
  <UContainer class="py-16">
    <h1 class="font-display text-4xl font-bold">
      Showcase
    </h1>
  </UContainer>
</template>
Page metaDefaultDescription
headertrueSet to false to skip rendering Header
footertrueSet to false to skip rendering Footer
layout'default'Layout used by the page

Pages whose path starts with /examples also skip the header and footer; that prefix is reserved for standalone component example previews.

Layouts

LayoutUsed by
defaultLanding, releases, showcase and custom pages; provides only a <main> container
docsDocs pages, including the left sidebar (navigation filter and docs navigation)

Create a file with the same name in app/layouts/ to override a built-in layout, or add new layouts for custom pages:

app/layouts/wide.vue
<template>
  <UMain>
    <UContainer class="max-w-screen-2xl">
      <slot />
    </UContainer>
  </UMain>
</template>
app/pages/playground.vue
<script setup lang="ts">
definePageMeta({
  layout: 'wide'
})
</script>
When overriding the docs layout, keep provide('docsFilterSearch', ...) and the DocsAsideLeftTop / DocsAsideLeftBody mounts, otherwise the sidebar filter and navigation stop working. See the docs.vue source.
Copyright © 2024 - 2026