36 lines
3.2 KiB
Markdown
36 lines
3.2 KiB
Markdown
# IPFS Content Retrieval
|
|
|
|
This document details the process of retrieving website content (markdown pages and images) from the IPFS network using a client-side IPFS library within the browser.
|
|
|
|
## Mechanism
|
|
|
|
The website relies on a JavaScript IPFS client library (e.g., `ipfs-http-client` or `js-ipfs`) running in the user's browser to interact with the IPFS network. Content is retrieved using its Content Identifier (CID), which is a hash of the content itself.
|
|
|
|
## Retrieval Process
|
|
|
|
1. **Obtaining the CID:** The IPFS hash (CID) for a specific piece of content (a markdown file or an image) is obtained from the metadata files, specifically the pages list metadata for markdown files. For images referenced within markdown, the CID needs to be resolved as described in the "Handling Image References in Markdown" section.
|
|
2. **Initializing the IPFS Client:** The browser-hosted website code initializes the IPFS client library, connecting to a local IPFS node (if available) or a public IPFS gateway.
|
|
3. **Fetching Content:** Using the obtained CID, the IPFS client's API is called to fetch the content. The specific API call will depend on the chosen IPFS client library (e.g., a method equivalent to `ipfs.cat(cid)` for file content).
|
|
4. **Processing Content:**
|
|
- **Markdown:** The retrieved markdown content (as a string or byte array) is processed by a markdown rendering library to convert it into HTML for display in the browser.
|
|
- **Images:** The retrieved image data is processed and displayed in an `<img>` tag. This typically involves creating a Blob URL or converting the image data to a Data URL that can be set as the `src` attribute of the `<img>` tag.
|
|
|
|
## Handling Image References in Markdown
|
|
|
|
Markdown files can contain image references. Since images are also stored on IPFS within the same collection, these references need to be resolved correctly.
|
|
|
|
- **Approach 1: Relative Paths:** Image references in markdown could use relative paths within the collection structure (e.g., `../images/image_name.png`). The website code would need to interpret these relative paths in the context of the current page's collection and resolve them to the correct image CID using a mechanism like an asset manifest or by convention (e.g., assuming image filenames correspond to CIDs in a separate lookup).
|
|
- **Approach 2: Direct CID References:** Image references in markdown could directly embed the IPFS CID of the image (e.g., ``). This simplifies retrieval but makes the markdown less human-readable and tightly couples it to IPFS CIDs.
|
|
- **Approach 3: Asset Manifest:** A separate JSON file within each collection (or a global asset manifest) could map image filenames to their IPFS CIDs. When rendering markdown, the website would look up image filenames in this manifest to get the correct CID for retrieval.
|
|
|
|
Approach 3 (Asset Manifest) is recommended for better organization and maintainability.
|
|
|
|
## Error Handling
|
|
|
|
The IPFS retrieval process should include robust error handling for cases such as:
|
|
|
|
- IPFS node not available or connection issues.
|
|
- CID not found on the network.
|
|
- Timeout during content retrieval.
|
|
|
|
Appropriate feedback should be provided to the user in case of retrieval failures. |