npm package: @sprig-and-prose/tutorial-svelte
Description: A calm SvelteKit package that transforms markdown files into paged tutorial routes
Latest version: 0.2.4

# @sprig-and-prose/tutorial-svelte

A calm Svelte/SvelteKit tutorial renderer.

This package turns a directory of Markdown files into small, paged tutorial routes.
It is designed for teaching small ideas that build gently, without requiring a custom format or a configuration file.

The filesystem is the structure.

---

## What this is

- A renderer for **paged markdown** (one file becomes multiple pages).
- A router-friendly model where **content paths mirror URL paths**.
- A calm default UX:
  - readable typography
  - low pressure navigation
  - gentle error states
  - optional directory “index” pages for orientation

## What this is not

- A general-purpose Markdown CMS
- A documentation framework
- A system with rich frontmatter, plugins, or a complex config graph

If you want heavy customization, use a general Markdown tool.
If you want calm structure that “just works,” this is for you.

---

## Conceptual model

### Content root

You choose a content root directory, for example:

```

src/content

```

Inside it, you create tutorial content:

```

src/content/
  greenhouse/
    arc1/
      intro.md
      noticing.md
      placing.md
      finishing.md
  another-tutorial/
...

```

### Routes mirror the content tree

Given a tutorial root (your site route root), for example:

```

/tutorial

```

The file:

```

src/content/greenhouse/arc1/intro.md

```

becomes:

```

/tutorial/greenhouse/arc1/intro/1
/tutorial/greenhouse/arc1/intro/2
/tutorial/greenhouse/arc1/intro/3
...

```

And:

```

/tutorial/greenhouse/arc1/intro

```

redirects to:

```

/tutorial/greenhouse/arc1/intro/1

````

---

## Pages inside a Markdown file

A single `.md` file becomes a **segment** made up of **pages**.

### Page boundaries

Each page begins with an H1 heading:

```md
# A first page title

Some text.

# A second page title

More text.
````

Each H1 creates a new page.

### Requirement: at least one H1

A markdown file must contain at least one `# ` H1 heading.

If a file contains **no H1 headings**, the tutorial will not render pages from it.
Instead, the UI should show a calm message like:

> “I couldn’t find any pages in this file yet.
> Pages start with `#` (H1) titles.”

This is intentional: it keeps tutorials structured and predictable.

---

## Navigation

Within a segment:

* “Next” and “Previous” are auto-generated based on page order in the file.
* The UI should be readable and low-pressure.
* Navigation should feel like **turning a page**, not completing a task.

### Linking between segments

Branching and rejoining are handled with normal hyperlinks.

For example, a “fork” page can link to two other segment routes:

* `/tutorial/greenhouse/arc1/branch-a/1`
* `/tutorial/greenhouse/arc1/branch-b/1`

A “rejoin” happens when both branches link back to a shared segment.

No special syntax is required.

---

## Directory index pages (orientation)

By default, directories are explorable.

If a user visits a directory path, for example:

```
/tutorial/greenhouse/arc1
```

the UI renders a calm index page listing child items (folders and markdown segments).

This page is intended to be an orientation aid, not a dense site map.

### Turning directory exploration off

Some tutorials should be experienced only via authored links.

For that, directory index pages can be disabled via an option:

* `enableDirectoryIndex: false`

When disabled:

* visiting `/tutorial/greenhouse/arc1` should return a gentle “not found” state
  (or a minimal message that directory exploration is disabled)
* direct segment routes (e.g. `/tutorial/greenhouse/arc1/intro/1`) should still work

---

## Error handling (calm by design)

### Page number out of range

If a user visits a page that doesn’t exist (e.g. `/tutorial/.../intro/99`), the UI should show:

* a calm message (“That page doesn’t exist.”)
* a suggestion (“Try the first page.”)
* a link back to `/1`

Avoid raw stack traces and avoid loud error styling.

### Missing file / unknown path

If a route does not map to any markdown file, the UI should show a calm “not found” state.

### Markdown file exists but has no H1

Show the “no pages found” message described above.

---

## SvelteKit integration expectations

This package is intended to be used from a SvelteKit catch-all route, for example:

```
src/routes/tutorial/[...path]/+page.ts
```

The integration should:

* map `path` to a markdown file under the content root
* parse markdown into pages by splitting on H1
* render one page at a time

---

## Options (minimal)

The package should support a small set of options:

* `routeBase` — the base route (e.g. `/tutorial`)
* `contentRoot` — the content directory (e.g. `src/content`)
* `enableDirectoryIndex` — default `true`

No other options are required for v1.

---

## Design goals

* Calm, human-first reading experience
* Minimal authoring rules
* No required config file
* Deterministic routing and navigation
* Supports branching through links, not through tutorial “logic”