Configuration

The following section is an overview of basic configuration for .

Most of the options discussed are specific to , for the rest of the available configuration options please check Vite's config reference.

Configuring Vite

You can configure Vite.js as usual using vite.config.ts, check Vite's plugins and config reference.

Alternatively, you can provide a vite option in iles.config.ts with the same options.

import { defineConfig } from 'iles'

export default defineConfig({
  vite: {
    plugins: [],
  },
})

Visit the Plugins section for more details about the pre-configured Vite.js plugins.

Configuring îles

You may provide an iles.config.ts configuration file to customize settings related to markdown, component resolution, and other îles-specific features.

You can leverage your IDE's intellisense with jsdoc type hints or use the defineConfig helper:

import { defineConfig } from 'iles'

export default defineConfig({
  siteUrl: 'https://iles-docs.netlify.app',
  jsx: 'preact',
})

drafts

• Type: boolean
• Default: true in development, false when building

Whether to include drafts in pages and documents.

By default drafts will be displayed during development, but will be excluded when building the site.

When disabled, drafts will also be excluded from useDocuments.

modules

• Type: IlesModuleOption[]

modules to apply in the site. Read the Plugins and Modules guide.

turbo (experimental)

• Type: boolean
• Default: false

Whether to enable SPA-like navigation for the site. See the guide for Turbo.

jsx

• Type: 'vue' | 'preact' | 'solid'
• Default: 'vue'

Which framework to use to compile .jsx and .tsx files.

prettyUrls

• Type: boolean
• Default: true

Whether to skip .html and trailing slashes in link hrefs and router paths.

Set prettyUrls: false to simplify the migration of an existing VitePress site without having to add redirects, or when deploying on services that don't support pretty urls (most do).

ssg

Options applied during site generation when running iles build.

ssg.beforePageRender

• Type: async (page: RouteToRender, config: AppConfig) => RouteToRender | void

This hook will be invoked before îles renders a page.

Modify page.rendered to alter the content of the page as needed.

ssg.onSiteRendered

• Type: async ({ pages: RouteToRender[], config: AppConfig }) => void

This hook will be invoked once îles has rendered the entire site.

ssg.manualChunks

Allows to configure how JS chunks for islands should be grouped.

ssg.sitemap

• Type: boolean
• Default:: true

Whether to generate a sitemap and reference it using a meta tag in all pages.

You must provide siteUrl to enable sitemap generation.

siteUrl

• Type: string

URL for the site in production, used to generate absolute URLs for the sitemap and social meta tags.

When set, it is exposed as site.url and site.canonical.

debug

• Type: boolean | 'log'
• Default: true

Whether to output more information about islands and hydration in development.

Your App

will pre-configure a Vue 3 app that will load any pages defined in the site.

You may provide additional configuration in src/app.ts, and leverage intellisense by using the defineApp helper.

import { defineApp } from 'iles'

export default defineApp({
  head ({ frontmatter, site }) {
    return {
      meta: [
        { property: 'author', content: site.author },
        { property: 'keywords', content: computed(() => frontmatter.tags) },
      ]
    }
  },
  enhanceApp ({ app, head, router }) {
    // Configure the app to add plugins.
  },
  router: {
    scrollBehavior (current, previous, savedPosition) {
      // Configure the scroll behavior
    }, 
  },
})

head

• Type: HeadObject | (context: AppContext) => HeadObject

Set the page title, meta tags, additional CSS, or scripts using @vueuse/head.

enhanceApp

• Type: (context: AppContext) => Promise<void>

A hook where you can add plugins to the Vue app, or do anything else prior to the app being mounted.

mdxComponents

• Type: MDXComponents | (context: AppContext) => MDXComponents

Provide an object that maps tag names in MDX to components to render.

import { defineApp } from 'iles'
import Image from '~/components/Image.vue'

export default defineApp({
  mdxComponents: {
    b: 'strong',
    img: Image,
  },
})

router

• Type: RouterOptions

Configure vue-router by providing options such as scrollBehavior and linkActiveClass.

socialTags

• Type: boolean
• Default: true

Some social tags can be inferred from the site.

Set it to false to avoid adding social tags such as og:title and twitter:description.

iles.config.ts Example

import { defineConfig } from 'iles'

import windicss from 'vite-plugin-windicss'

export default defineConfig({
  siteUrl: 'https://iles-docs.netlify.app',
  extendFrontmatter (frontmatter, filename) {
    if (filename.includes('/posts/'))
      frontmatter.layout = 'post'
  },
  markdown: {
    remarkPlugins: [
      'remark-gemoji',
    ],
  },
  modules: [
    '@islands/icons',
    '@islands/headings',
    '@islands/prism',
  ],
  vite: {
    plugins: [
      windicss(),
    ],
  },
})