Installation

This guide will help you install and set up Ptero in your project. Choose the installation method that best fits your workflow.

Prerequisites

Before installing Ptero, make sure you have:

  • Node.js version 18.0 or above
  • pnpm, npm, or yarn package manager
  • A SvelteKit project (or willingness to create one)

Quick Start

The fastest way to get started is using the Ptero CLI in an existing SvelteKit project:

# Install Ptero packages
pnpm add -D ptero-cli mdsvex

# Run the initialization command
pnpm ptero init

# Start your development server
pnpm dev

Visit http://localhost:5173/docs/latest to see your documentation site.

:::note The ptero init command is idempotent - you can run it multiple times safely. It will only add missing files and configurations. :::

Starting from Scratch

If you don’t have a SvelteKit project yet:

# Create a new SvelteKit project
pnpm create svelte@latest my-docs
cd my-docs

# Install dependencies
pnpm install

# Add Ptero
pnpm add -D ptero-cli mdsvex
pnpm ptero init

# Start developing
pnpm dev

What Gets Installed

When you run ptero init, the CLI will:

  1. Install docs packages (if not already present):

    • mdsvex - Markdown processing with Svelte support
    • UI components added via ptero add <component>

  2. Create configuration files:

    • ptero.config.ts - Main configuration file
    • Updates to svelte.config.js for MDsveX integration

  3. Scaffold directory structure:

    src/
├── content/
│   └── docs/              # Your markdown files go here
│       ├── intro/
│       │   └── index.md
│       └── guides/
│           └── getting-started.md
├── routes/
│   └── docs/
│       ├── [version]/
│       │   ├── +layout.svelte
│       │   ├── +layout.server.ts
│       │   ├── +page.svelte
│       │   └── [...slug]/
│       │       ├── +page.svelte
│       │       └── +page.server.ts

  4. Add example content:

    • Sample markdown files to help you get started
    • Frontmatter examples
    • Basic navigation structure

Manual Installation

If you prefer more control over the installation process:

Step 1: Install Dependencies

pnpm add -D mdsvex

Step 2: Configure MDsveX

Update your svelte.config.js:

import adapter from '@sveltejs/adapter-auto';
import &#123; vitePreprocess &#125; from '@sveltejs/vite-plugin-svelte';
import &#123; mdsvex &#125; from 'mdsvex';

/** @type &#123;import('@sveltejs/kit').Config&#125; */
const config = &#123;
	extensions: ['.svelte', '.md'],

	preprocess: [
		vitePreprocess(),
		mdsvex(&#123;
			extensions: ['.md'],
			layout: &#123;
				docs: './src/lib/layouts/DocsLayout.svelte'
			&#125;
		&#125;)
	],

	kit: &#123;
		adapter: adapter()
	&#125;
&#125;;

export default config;

Step 3: Create Configuration

Create ptero.config.ts in your project root:

import type &#123; PteroConfig &#125; from 'ptero-core';

const config: PteroConfig = &#123;
	site: &#123;
		title: 'My Documentation',
		description: 'Comprehensive documentation for my project',
		url: 'https://docs.example.com'
	&#125;,
	versions: &#123;
		current: 'latest',
		available: [&#123; id: 'latest', label: 'Latest', status: 'latest' &#125;]
	&#125;,
	sidebar: &#123;
		sections: [
			&#123;
				title: 'Introduction',
				items: [&#123; title: 'Getting Started', slug: 'intro/getting-started' &#125;]
			&#125;
		]
	&#125;
&#125;;

export default config;

Step 4: Set Up Routes

Create the following route structure:

src/routes/docs/[version]/+layout.server.ts:

import &#123; loadSidebar, loadConfig &#125; from 'ptero-core';

export async function load(&#123; params &#125;) &#123;
	const config = await loadConfig();
	const sidebar = await loadSidebar(params.version);

	return &#123;
		sidebar,
		config,
		version: params.version
	&#125;;
&#125;

src/routes/docs/[version]/+layout.svelte:

&lt;script lang="ts"&gt;
	let &#123; children, data &#125; = $props();
&lt;/script&gt;

&lt;DocsLayout sidebar=&#123;data.sidebar&#125; currentVersion=&#123;data.version&#125;&gt;
	&#123;@render children()&#125;
&lt;/DocsLayout&gt;

src/routes/docs/[version]/[...slug]/+page.server.ts:

import &#123; loadDoc &#125; from 'ptero-core';
import &#123; error &#125; from '@sveltejs/kit';

export async function load(&#123; params &#125;) &#123;
	const doc = await loadDoc(params.version, params.slug);

	if (!doc) &#123;
		throw error(404, 'Page not found');
	&#125;

	return &#123; doc &#125;;
&#125;

src/routes/docs/[version]/[...slug]/+page.svelte:

&lt;script lang="ts"&gt;
	let &#123; data &#125; = $props();
&lt;/script&gt;

&lt;svelte:component this=&#123;data.doc.component&#125; /&gt;

Step 5: Create Content

Create your first documentation file at src/content/docs/intro/getting-started.md:

---
title: Getting Started
description: Learn the basics
section: Introduction
order: 1
---

# Getting Started

Welcome to your documentation!

Add components (optional)

Use the CLI to pull in prebuilt UI components (shadcn-style):

pnpm ptero add avatar

Package Managers

Ptero works with all major package managers:

pnpm add -D ptero-cli mdsvex
pnpm ptero init

npm

npm install --save-dev ptero-cli mdsvex
npm exec ptero init

yarn

yarn add -D ptero-cli mdsvex
yarn ptero init

Troubleshooting

Port Already in Use

If port 5173 is already in use, you can specify a different port:

pnpm dev -- --port 3000

MDsveX Not Processing Files

Make sure your svelte.config.js includes .md in the extensions array and has mdsvex in the preprocess chain.

TypeScript Errors in Config

Ensure you have the correct types installed:

pnpm add -D @types/node

Build Errors

If you encounter build errors, try clearing the .svelte-kit directory:

rm -rf .svelte-kit
pnpm dev

Next Steps

Now that you have Ptero installed:

Upgrading

To upgrade to the latest version of Ptero:

pnpm update ptero-cli

Check the changelog for breaking changes before upgrading major versions.

Built with Ptero