Development 💻

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

Default App Structure 📂

src/
├── 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.

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:

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

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

  <Song :title="$frontmatter.title" :src="$frontmatter.audio"/>
</template>

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()
</script>

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()
</script>

<template>
  <h1>Posts</h1>
  <article v-for="post of posts" :key="post.href">
    <time :datetime="post.date.toISOString()">{{ formatDate(post.date) }}</time>
    <h2>
      <a :href="post.href">{{ post.title }}</a>
    </h2>
    <component :is="post" excerpt/>
  </article>
</template>

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: 'https://iles-docs.netlify.app',
})

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.