Filename, document title and first heading

This article explains the relationship between the filename, title, and first heading in documents, folders and URLs.

Filename

All documents and folders have a filename. However, because they might be physically stored on the file system of the host server, they mustn’t have names that violate the naming rules of the host operating system.

Creating documents

When creating PSML documents, the document title is used to generate the filename of the document or folder. The default rules include:

• Character folding to replace characters that have diacritical marks by the character without the mark, (for example, ‘é’ -> ‘e’).
• Case folding transform all characters to lower case.
• Replace non-ASCII and space characters by an underscore ‘_’ .
• Trimming to remove leading and trailing space, ‘_’ or ‘-’ in value.

Example: When creating the document with title “At the café!”, the filename is “at_the_cafe.psml”.

Document title

To overcome the limitations of the filename, all PageSeeder documents and URLs, also have a document title. The document title has no restrictions on the characters that it can display, so it can be used to provide a user-friendly name for the document to users in the user interface.

If the document title isn’t specified, it inherits the name of the file. This generally occurs when files are uploaded (for example, images).

Uploading documents

When uploading a document, the filename is already determined by the file you’re uploading. For a PSML document, the document title is specified in the content.

For other types of documents (such as images, PDF or Word documents), the document title is usually the same as the filename unless:

• The uploaded document was exported from PageSeeder and includes a metadata PSML document which might include a document title, labels and other metadata.
• The media type has an associated media template which tells PageSeeder how to generate the document title from the file’s metadata (for example, EXIF or DOCX metadata).

The first heading

The document title is not to be confused with the first heading in the content of PSML documents, which might be sometimes casually referred to as the “document title”.

When a PSML document is created, a heading in the content is generally populated with the document title property This is based on the document template and is the case for all built-in document types. Unless either the document title or the first heading have been edited subsequently, they usually have the same value.

PageSeeder warns when the Document title and the first heading do not match.

The first heading is primarily used for the table of contents. Although there is no restriction on the length of a heading, using excessively long headings is discouraged.