43 lines
2.7 KiB
Markdown
43 lines
2.7 KiB
Markdown
# 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). |