...

specs/page_structure.md

@@ -0,0 +1,43 @@
+# 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).