pages-theme-eox

Vitepress theme for EOX branded pages.

Usage

npm install -D @eox/pages-theme-eox

// .vitepress/theme/index.js
import EOX from "@eox/pages-theme-eox"

export default {
  extends: EOX
};

See also the Vitepress Docs.

Configuration

This theme supports standard VitePress Default Theme Configuration with some specific adaptations.

Navigation Bar

The Navigation Bar follows the Default Theme Nav structure with the following differences:

| Feature | Supported | Notes | | :---------------- | :-------- | :------------------------------------------------------------------------------------------ | | Links | ✅ | Standard { text, link } structure. | | Dropdowns | ✅ | Standard { text, items: [] } structure, supports nesting. | | Active Match | ✅ | activeMatch regex strings are supported. | | Target/Rel | ✅ | target and rel attributes are supported. | | Buttons | ✨ | Custom: Add action: 'primary' (or 'secondary') to a nav item to style it as a button. | | Logo | ⚠️ | Must be an object with light/dark paths: { light: '...', dark: '...' }. | | Social Links | ✅ | Valid socialLinks will be displayed in the navbar. | | Custom Components | ❌ | Embedding custom components directly in the nav array is not supported. |

Example Configuration

// .vitepress/config.js
export default {
  themeConfig: {
    logo: {
      light: "/logo-light.svg",
      dark: "/logo-dark.svg",
    },
    nav: [
      { text: "Home", link: "/" },
      {
        text: "Products",
        items: [
          { text: "Product A", link: "/a" },
          { text: "Product B", link: "/b" },
        ],
      },
      // Custom generic button style
      { text: "Contact Us", link: "/contact", action: "primary" },
    ],
  },
};

General Configuration

The following standard VitePress configurations are handled as follows:

• Site Title: Explicitly disabled (siteTitle: false). The theme relies on the logo for branding.
• Logo: Used for branding. Must be configured as an object { light: string, dark: string }.
• Nav: Fully supported (see above).
• Footer: Supported. The theme uses theme.footer.copyright for the copyright text.
• Dark Mode: The theme enforces a specific appearance. appearance: false is set in the base config.

Internationalization (i18n)

This theme leverages VitePress's native i18n capabilities and extends them with a simplified configuration via brandConfig.

Multi-language Routing

You can define multiple locales in your brandConfig. The theme will automatically generate the corresponding VitePress routes and display a language switcher in the navigation bar.

// brandConfig
{
  i18n: {
    locale: {
      en: {
        "Read more about": "Read more about",
        "Contact us": "Contact us"
      },
      de: {
        "Read more about": "Mehr lesen über",
        "Contact us": "Kontaktieren Sie uns"
      }
    },
    currentLocale: "en" // This language will be at the root URL (/)
  }
}

Translation Pattern

The theme uses a "string-as-key" pattern. Most hardcoded UI elements (buttons, footer labels, etc.) use their English text as a lookup key. If a translation is provided in the brandConfig.i18n.locale object, it will be used; otherwise, it falls back to the original English text.

Nested keys are also supported via dot-notation if needed (e.g., legal.privacy).

Language Switcher

• Desktop: Appears as a translate icon in the top navigation bar.
• Mobile: Appears as a dedicated section within the mobile menu.
• The current language is automatically detected based on the URL path (e.g., /de/ for German).

Note on Documentation Features: This theme is primarily designed for landing pages and product showcases.

• Social Links and TOC are supported as described in the VitePress documentation.
• Sidebar and Outline are automatically enabled for the doc layout, whereas the page layout doesn't have them.
• Other features like Edit Link, Last Updated, and Algolia Search are not currently integrated into the custom Layout.vue and may not function as expected if configured.

Cookie Consent

This theme includes built-in cookie consent management integrated with Matomo (Piwik) analytics.

• Cookie Banner: Automatically displayed if brandConfig.analytics is present.
• Cookie Settings: a /cookie-settings page is automatically handled to allow users to review and toggle optional cookies.

Analytics Configuration

To enable the cookie banner and analytics tracking, ensure your brand config includes:

// brandConfig
{
  analytics: {
    siteId: "YOUR_MATOMO_SITE_ID";
    // The tracker URL is hardcoded to "https://nix.eox.at/piwik/" in vitepressConfig.mjs
  }
}

Layout & Components

The theme provides several built-in components and layout features. Some are driven by frontmatter configuration, while others can be used directly in your Markdown files.

Hero Section

To add a Hero section to the top of a page, use the hero frontmatter object.

---
hero:
  title: "Welcome to My Site"
  tagline: "Building the future of things"
  image:
    src: "/hero-image.png"
    alt: "Hero Image"
  actions:
    - text: "Get Started"
      link: "/start"
      type: "primary"
    - text: "Learn More"
      link: "/about"
      type: "secondary"
---

Feature Section

Use the <FeatureSection> component to highlight specific features.

<FeatureSection
  title="My Feature"
  tagline="This is an amazing feature"
  icon="mdi-star"
  flipped
>
  <template #default>
    <p>Detailed description of the feature.</p>
  </template>
  <template #actions>
    <a href="/docs" class="btn">Documentation</a>
  </template>
</FeatureSection>

Pricing Table

A flexible pricing table component.

<PricingTable
  :config="{
    plans: [
      {
        title: 'Basic',
        price: '€0',
        features: ['Feature 1', 'Feature 2'],
        link: { text: 'Sign Up', href: '/signup' }
      },
      {
        title: 'Pro',
        price: '€99',
        features: ['Everything in Basic', 'Feature 3'],
        link: { text: 'Go Pro', href: '/pro' },
        active: true
      }
    ]
  }"
/>

Other Components

CTA Section

A Call-to-Action section typically placed at the bottom of a page to encourage user engagement.

<CTASection
  title="Ready to get started?"
  tagline="Join thousands of others today."
  primary-button="Sign Up Now"
  primary-link="/register"
  secondary-button="Contact Sales"
  secondary-link="/sales"
  alt-button="Read Documentation"
  alt-link="/docs"
  dark
/>

Logo Section

Displays a grid of client or partner logos. It automatically handles logo sizing.

<LogoSection
  :logos="[
    { image: '/logos/client1.png', alt: 'Client 1', link: 'https://client1.com' },
    { image: '/logos/client2.png', alt: 'Client 2' }
  ]"
  base-height="4"
  strength="1"
/>

Data Table

An interactive table with expandable rows. The summary object keys must match the headers provided.

<DataTable
  :headers="['Name', 'Type', 'Status']"
  :data="[
    {
      summary: { Name: 'Task A', Type: 'Cron', Status: 'Active' },
      content: 'Detailed description of Task A...'
    },
    {
      summary: { Name: 'Task B', Type: 'Trigger', Status: 'Paused' },
      content: 'Detailed description of Task B...'
    }
  ]"
/>

Features Gallery

A grid layout for feature cards. Automatically used on pages under features/, but can be used manually with custom cards.

<FeaturesGallery
  section-title="All Features"
  background="surface-container-low"
  :cards="[
    {
      id: 1,
      title: 'Global Coverage',
      content: 'Access data from anywhere.',
      icon: 'mdi-earth'
    },
    {
      id: 2,
      title: 'Real-time',
      content: 'Updates as they happen.',
      link: { text: 'Learn more', href: '/real-time' }
    }
  ]"
/>