Files and documents#

Files are essential to Documatt. This guide explains the difference between files and documents, how to navigate file structures, and the basics of creating, editing, and managing files and folders.

Introduction#

Before proceeding, let’s learn a few key terms, as they will help you better understand Documatt.

The book in Documatt is composed of files and folders, similar to those on your computer. However, for better distinction of their type, files are referred to either as files or images.

  • documents - text files written in either Markdown or reStructuredText syntax with extension .md or .rst.

  • images - picture formats JPG (extensions .jpg, .jpeg), PNG (.png), SVG (.svg), and GIF (.gif). Max size is limited to 1 MB.

Not supported file types#

Except for documents and images, Documatt doesn’t allow you to upload files of other types, such as archives, videos, or PDFs.

However, you can always host them elsewhere and use their public URL to insert them into documents.

Root document (index)#

The root document is the first page that a book’s readers will see. It’s often called index because its file is index.md (Markdown) or index.rst (reStructuredText).

  • There is always exactly one root document per book.

  • The root document cannot be renamed, moved, or deleted.

  • It’s called a root document because it’s located in the root folder (/).

File naming rules#

In the names of files and folders, only the following letters can appear:

  • lowercase a-z, uppercase A-Z, numbers 0-9

  • exclamation mark !, hyphen -, and underscore _

It means any other characters like national letters or special characters like ?, # are forbidden. It’s to avoid problems because the filename becomes a URL address when you publish your book.

For example, the following are valid and invalid filenames:

✅ billing
✅ 4billing
✅ billing2
✅ !important
✅ install-guide
✅ install-guide_
✅ install_guide!
✅ _notes

❌ français
❌ Українська
❌ ?not_finished
❌ #tempfile
❌ .private
❌ shall\tass

Using the file explorer#

The file explorer is a tool for managing files and folders. It’s part of the editor view.

If you don’t see it, switch among editor layouts (see editor layouts):

To select a folder where you want to manipulate files:

Create a document or folder#

In the file explorer, you can create a new item.

  1. Select a folder where you want to create a document or folder.

  2. Click on 1 and enter a document or folder name 2.

  3. The newly created file will have 4 name. Confirm with 3.

Upload an image#

To insert an image into a document, you need to upload it and use its file path in the image directive markup.

To upload an image, in the file explorer:

  1. Select a folder where you want to upload an image.

  2. Click on the 1 tab and the 2 button to select a file on your computer to upload.

Rename, move, and delete#

The remaining buttons on the file explorer allow you to

  • rename file or folder 1

  • move file or folder 2

  • delete file or folder 3

Caution

Please note that deleting a file or folder is permanent and immediate. After a deletion, it cannot be restored.