Development ๐Ÿ’ป

In this section, we'll cover the basics to start building an รฎles application.

Default App Structure ๐Ÿ“‚

โ”œโ”€โ”€ components/
โ”‚    โ”œโ”€โ”€ ReadingTime.vue
โ”‚    โ””โ”€โ”€ Author.vue
โ”œโ”€โ”€ layouts/
โ”‚    โ”œโ”€โ”€ default.vue
โ”‚    โ””โ”€โ”€ post.vue
โ”œโ”€โ”€ pages/
โ”‚    โ”œโ”€โ”€ posts/
โ”‚    โ”‚    โ”œโ”€โ”€ intro.mdx
โ”‚    โ”‚    โ””โ”€โ”€ goodbye.mdx
โ”‚    โ”œโ”€โ”€ about.vue
โ”‚    โ””โ”€โ”€ index.mdx
โ”œโ”€โ”€ app.ts
โ””โ”€โ”€ site.ts

By default, srcDir is aliased as ~/ or @/. For example:

import { useDark } from '~/logic/dark'
<img src="@/assets/logo.svg"/>

Components ๐Ÿงฑ

Components in the src/components dir will be auto-imported on-demand, powered by unplugin-vue-components.

รฎles extends this so that you don't need to import components in MDX files.

Pages ๐Ÿ›ฃ

Routes will be auto-generated for files in the src/pages dir with the same file structure.

Pages can be Vue components or MDX files, and may specify frontmatter and route metadata.

You may use components inside MDX, and access any properties defined in the frontmatter:

title: Song for You
audio: /song-for-you.mp3

I've recently recorded a song, listen:

<Song title={title} src={audio}/>

In Vue single-file components you can use a <page> block to define frontmatter:

title: Song for You
audio: /song-for-you.mp3

  <p>I've recently recorded a song, listen:</p>

  <Song :title="$frontmatter.title" :src="$"/>
Page Hooks ๐ŸŽฃ

You can customize all pages using the extendFrontmatter and extendRoute hooks.

Using Page Data

You may access information about the current page using the usePage composition API helper, or by using the $frontmatter or $meta global properties.

  • frontmatter: The frontmatter of an MDX document or Vue component (in <page>)
  • meta: Information about the page, including href, filename, and lastUpdated
<script setup>
import { usePage } from 'iles'

const { frontmatter, meta } = usePage()
Composables are auto-imported
You don't need to import usePage, useRoute, useHead, or definePageComponent.

Glob Imports

When rendering collections or index pages, you can leverage useDocuments to conveniently access multiple page components and their data.


export function usePosts () {
  const posts = useDocuments('~/pages/posts')
  return computed(() => posts.value.sort(byDate))

Page data is available directly in the component modules:

<script setup lang="ts">
import { usePosts } from '~/logic/posts'

const posts = usePosts()

  <article v-for="post of posts" :key="post.href">
    <time :datetime="">{{ formatDate( }}</time>
      <a :href="post.href">{{ post.title }}</a>
    <component :is="post" excerpt/>

Layouts ๐Ÿ“

Components in the src/layouts dir will be available as layouts, and they should provide a default <slot/>.

Pages may specify a layout using the layout property in frontmatter:

layout: post

Layouts and Vue pages can also specify a parent layout using a layout attribute in the template:

<template layout="post">

The default layout will be used for all pages unless specified.

Pages may opt-out by specifying layout: false

Layout files must be lowercase, as in post.vue or default.vue.

Site ๐ŸŒ

src/site.ts can be used to provide site-wide information such as title, description, etc.

It can be accessed as $site in component instances, or by using usePage.

It's also displayed in the page information in Islands devtools.

export default {
  title: 'About',
  description: 'Learn more about what we do',

Sitemap ๐Ÿ—บ

A sitemap can be automatically generated for your site, all you need to do is configure siteUrl. That will also make it available as site.url and site.canonical.

import { defineConfig } from 'iles'

export default defineConfig({
  siteUrl: '',

If you would like to opt-out, you can disable it explicitly:

export default defineConfig({
  ssg: {
    sitemap: false

Devtools ๐Ÿ› 

Page information is available in a debug panel, similar to VitePress, but you may also access an Islands inspector in Vue devtools.

This can be useful when debugging islands hydration.

Last Updated: