2.7 KiB
Page and Collection Structure
This document describes the organization of markdown pages and associated image files into collections, and how these files are addressed within the website.
Collections
A collection is a logical grouping of related content, typically consisting of one or more markdown files and associated image files. Collection directories are identified by the presence of a .collection file in the root of the directory.
On IPFS, a collection is represented as a directory (or an IPFS object acting as a directory).
- Each collection resides in its own "folder" on IPFS.
- All files directly within a collection directory (excluding subfolders) are considered part of the collection.
- All filenames (markdown and images) within a single collection must be unique.
- Subfolders within a collection are ignored for the purpose of page addressing and content retrieval as defined in the pages list metadata.
Page Addressing
Markdown pages are addressed using a combination of their collection name and filename. This forms a unique path that is used in the navigation metadata (navbar and footer) and the pages list metadata.
The format for a page path is collection_name/filename_without_extension.
For example, a markdown file named introduction.md within a collection named introduction would have a page path of introduction/introduction.
File Naming and Normalization
All collection names and filenames (for both markdown and images) must adhere to the following conventions:
- Lowercase: All characters must be lowercase.
- Snake Case: Words should be separated by underscores (
_).
Before processing, all filenames within a collection directory must be normalized to meet these conventions.
Examples:
- Valid collection names:
introduction,our_story,legal - Valid filenames:
introduction.md,privacy_policy.md,team_photo.png
Pages List and File Resolution
The pages list metadata (pages_list.json) serves as the central index for all available markdown pages. Each entry in this list maps a unique page path (collection/filename_without_extension) to the IPFS hash of the corresponding markdown file.
When the website needs to display a page based on its page path (e.g., from a navbar link), it looks up the path in the pages list to retrieve the IPFS hash of the markdown file.
Image files associated with a markdown page are expected to reside within the same collection (IPFS directory). Resolving image references within a markdown file to their specific IPFS hashes is handled separately, as described in the specs/content_retrieval.md document (preferably using an asset manifest within the collection).