# Files and folders

> Create, name, rename, move, and bulk-manage documents and folders up to five levels deep in your workspace.

Source: https://hyperclay.com/docs/files/

You organize your documents and uploaded files in folders inside your workspace. You can nest folders up to five levels deep, rename or move items individually, or select up to 100 items at once in the files table to move or delete them together.

## Name rules

When you type a document or folder name in a create or rename dialog, Hyperclay formats it as you type:

- Uppercase letters are converted to lowercase.
- Characters outside lowercase letters (`a` to `z`), numbers (`0` to `9`), hyphens (`-`), and underscores (`_`) are replaced with hyphens.
- Consecutive hyphens collapse into a single hyphen, and leading or trailing hyphens are trimmed.
- Document names must end in `.html` or `.htmlclay`. If you omit the extension, `.html` is added automatically. Folder names do not take an extension.

When the dialog adjusts what you typed, it shows **Saved as** followed by the formatted name below the field. If the resulting name is invalid, the dialog displays the reason and disables the submit button:

- A name cannot be empty or longer than 255 characters.
- A name cannot start or end with a hyphen, or contain consecutive hyphens.
- A single underscore (`_`) and system names such as `con` are reserved.

Uploaded files keep their original names instead of being slugged. Upload names can be up to 255 bytes and may contain letters, numbers, spaces, and `._()[]{}-!@#$%^&+=`, but cannot contain `/ \ < > : " | ? *` or reserved system names.

## Folder depth

Folders can nest up to 5 levels below the root of your workspace:

- Creating a sixth folder level is refused with **Maximum folder depth reached (5 levels)**.
- Moving a folder to a destination where it or its subfolders would pass 5 levels is refused with **Moving would exceed maximum folder depth (5 levels)**.
- You cannot move a folder into itself or into any of its own subfolders.

The top-level `uploads` folder holds attachments for your documents and is locked: it cannot be renamed, moved, or deleted. See [Uploads](https://hyperclay.com/docs/uploads/).

## Create a document or folder

To create a folder:

1. Open the **New** menu and start the **Create folder** dialog.
2. Enter a name in **Folder name**.
3. Click **Create folder**.

To create a document, open **New** and click **New document** to pick a starter in the gallery; see [Templates](https://hyperclay.com/docs/templates/).

To copy an existing document, open its **Actions for** row menu and click **Duplicate**. The default name is `<name>-copy.html`, trimmed if needed to stay within 255 characters.

## Rename a document or folder

Account owners and team editors can rename any document, upload, or normal folder (team viewers cannot rename items). A file a document uploaded, and that document's own folder inside `uploads`, cannot be renamed or moved by themselves: they move and rename with their document.

1. In the files table, open the item's **Actions for** menu and choose **Rename** (or rename the item inline in the sidebar file tree).
2. Enter the new name in the **Name** field.
3. Click **Rename**.

## Move a document or folder

Account owners and team editors can move items between folders:

1. Open the item's **Actions for** menu and click **Move to folder…**.
2. In the **Move** dialog, choose a destination folder (pick **Files** to move the item to the root of your workspace).
3. Click **Move**.

Moving and renaming happen in a single atomic operation, so a move either finishes completely or leaves the item untouched.

> [!WARNING]
> Moving an item changes its path-based URL, including the paths of everything inside a moved folder. Update any links that point to the old path. Pictures and files a document uploads are stored in its own `uploads/assets-document-<id>/` folder, named after the document's id, so they keep working when the document is renamed or moved.

## Bulk select

In the files table, use the row checkboxes to act on multiple items at once. Only rows you have permission to move or delete can be selected.

- Click individual checkboxes to add or remove rows, or Shift-click a checkbox to select a range of rows.
- Click the header checkbox (**Select all**, or **Select loaded items** when more rows remain) or press Cmd+A (Ctrl+A on Windows and Linux) to select all loaded rows.
- Press Escape or click **Clear selection** in the floating bar to clear your selection. Switching folders also clears the selection.

When one or more rows are selected, a floating bar shows **`<N>` selected** and offers two actions: **Move to folder** and **Delete**. Bulk operations process 1 to 100 items per request, and larger selections are split into batches of 100 automatically.

### Move to folder

Click **Move to folder** in the floating bar to open the **Move `<N>` items** dialog. Pick a destination folder and click **Move here**. Moving a folder moves everything inside it and updates path-based URLs for all moved items.

### Delete

Click **Delete** in the floating bar to open the **Delete `<N>` items?** confirmation dialog, then click **Delete `<N>` items**. Every selected item moves to [Trash](https://hyperclay.com/docs/trash/), and any selected folder includes everything inside it.

When a bulk move or delete finishes, a notification reports **Moved `<N>` items.** or **Deleted `<N>` items.** If any items could not be changed, the notice reports **`<N>` items did not change.** with the reason for each file and a **Retry failed or unattempted** button.
