# IPLD Documentation and Specifications Repository

> The ipld/ipld repository builds the IPLD website and contains its specifications, design work, and related documentation. It is intended for contributors working on content-addressed data formats, not as an application runtime or data-processing library.

**ipld/ipld** — This repo holds Website and Specs at https://ipld.io

- Repository: https://github.com/ipld/ipld
- Website: https://ipld.io/
- Stars: 1,347 · Forks: 171
- Language: Nunjucks
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/ipld-ipld

## What the ipld/ipld Repository Contains

IPLD stands for InterPlanetary Linked Data and is described by the README as a series of standards and formats for describing data with an emphasis on content addressing. The repository is therefore not an IPFS node, a graph database, or an application library. Its purpose is to define and explain the data model and related formats through specifications and documentation.

The repository combines several kinds of source material. The `docs/` and `specs/` directories hold published documentation and specifications, while `design/` contains design work. Other visible areas include `libraries/`, `tools/`, `notebook/`, and `media/`. This broad layout makes the repository relevant to people who need to understand IPLD as well as contributors who want to change its published explanation or normative content.

The intended users are IPLD implementers, documentation contributors, specification authors, and developers designing decentralized applications that need shared data formats. The README also directs readers who only want to consume the material to the site at `https://ipld.io/`. That distinction matters because cloning the repository is mainly useful when the reader intends to inspect source files, run the site locally, or prepare a patch. The repository is not archived, and its last push was on 2026-10-02.

## How the Eleventy Site Pipeline Handles IPLD Content

The website is generated with Eleventy, as shown by the dependencies in `package.json`. The `build` script changes into `.site` and runs `eleventy`, while both `start` and `dev` run Eleventy in serve mode. This arrangement separates authored site content and configuration under `.site` from generated output under `.site/_output`.

The documentation workflow has more than rendering. During `npm install`, the `postinstall` script runs `npm run fetch-hyperlink`. Platform-specific scripts download the `hyperlink` binary from version `0.1.15` and place it at `.site/_tools/hyperlink`. On Linux, the binary receives executable permission. The test script then passes the generated output to that utility with `--check-anchors --sources=.`. Based on the script definition, the test is specifically concerned with link integrity and anchors rather than functional behavior of the published specifications.

The published site also contains the specifications themselves. A separate script, `build:schema-schema`, runs `ipld-schema to-json` against `specs/schemas/schema-schema.ipldsch` and redirects the output into `specs/schemas/schema-schema.ipldsch.json`. This shows that some repository files are generated from IPLD schema sources. It also creates an upgrade concern: contributors changing the schema source must know whether the corresponding JSON artifact needs to be regenerated before review.

Publishing is tied to repository integration rather than a release package. The README says that merging to `master` allows Fleek to perform the remaining work, and the `publish` script deliberately exits with an error after printing `Just push!  Fleek will pick it up from github.` There are no GitHub releases for this repository, so consumers should not expect tagged software releases or versioned site archives here.

## Installing the IPLD Documentation Site on Node.js

The README requires Node.js 16 or newer. Install dependencies from the repository root with the documented command:

```bash
npm install
```

This does more than install JavaScript packages. The `postinstall` entry runs `fetch-hyperlink`, whose Linux-specific script downloads a platform binary using `wget`. A contributor therefore needs an environment capable of running that script and presenting the downloaded file at `.site/_tools/hyperlink`. The documented package scripts have separate definitions for `darwin` and `linux`, but the repository information does not define a Windows downloader.

After installation, generate the site with:

```bash
npm run build
```

The command runs Eleventy from `.site` and is the same build invoked by the Makefile's `build` target. If generated output is present from an earlier build, the documented cleanup command is:

```bash
npm run clean
```

That script removes `.site/_output`. It does not clear `node_modules` or downloaded tools, so cleanup should not be treated as a complete reset of the working environment.

## Previewing Changes and Checking IPLD Documentation Links

A first local review starts with the documented development server:

```bash
npm run start
```

This command runs `cd.site && eleventy --serve`. The same behavior is exposed as `npm run dev` in `package.json`, while the Makefile provides `make dev`. The repository does not document a fixed port, so a contributor should rely on the address printed by Eleventy rather than assume one.

Before submitting a patch, run the link integrity check:

```bash
npm test
```

The test command invokes `.site/_tools/hyperlink` against `.site/_output` with anchor checking enabled and repository sources supplied through `--sources=.`. It therefore needs a build output and the downloaded executable. The test does not appear, from its script definition, to validate the semantics of every specification, execute application examples, or confirm that generated schema JSON is synchronized. It is a focused documentation check.

The Makefile can combine the standard sequence through `make all`, whose targets are `prepare build test`. For direct schema regeneration, the repository defines:

```bash
npm run build:schema-schema
```

This invokes `ipld-schema to-json`, selects `-t specs/schemas/schema-schema.ipldsch`, and writes `specs/schemas/schema-schema.ipldsch.json`. The project does not document when this generated file must be committed, so contributors should inspect repository conventions and the affected specification rather than assume every schema edit requires regeneration.

## Specification Editing Risks and Unsupported Runtime Use

The largest limitation is the distinction between defining a format and implementing it. This repository can document IPLD and publish specifications, but its package description is `IPLD Docs Site`, its package is marked `private`, and its listed dependencies focus on Eleventy and documentation utilities. The listed package scripts do not expose an API for encoding application data, resolving Content Identifiers, loading linked objects, or storing IPLD data. An engineer expecting those operations should choose an implementation repository instead.

Specification changes also carry editorial and compatibility concerns. A textual change can alter implementation guidance, examples, schema behavior, or cross-document terminology even when Eleventy builds successfully. The `npm test` script checks hyperlinks and anchors, but it does not establish that a proposal is technically approved or compatible with existing implementations. The README recommends discussing changes in an issue or one of the linked community chat venues before preparing patches. That process is especially relevant when a documentation edit affects normative behavior rather than wording.

The build scripts expose platform-specific constraints as another failure mode. `fetch-hyperlink:darwin` and `fetch-hyperlink:linux` target x86_64 binaries. No Windows variant appears in `package.json`, and no fallback behavior for an unsupported operating system is documented. Contributors on Windows, or on an architecture that cannot run the downloaded x86_64 executable, may be unable to use the documented post-install and test path without separate work. The repository also does not document a rollback procedure for website publishing.

## IPLD Specifications Versus Conventional JSON Documentation

A practical alternative is to maintain a conventional site built around JSON or Markdown without IPLD specifications. That approach may be simpler when a team only needs formatted prose, JSON examples, or local links. It does not attempt to define shared semantics for content-addressed and linked data, but it avoids the need to reason about IPLD schema sources, generated schema artifacts, and specification-level compatibility.

This repository takes the opposite approach. IPLD is explicitly a collection of standards and formats for content-addressed data descriptions, and the repository separates design work, documentation, specifications, and tooling. That separation is useful when the goal is a common vocabulary that multiple decentralized applications can implement. It is unnecessary overhead when a private website has no need for interoperable data definitions.

For IPLD implementers, the value is coordination rather than local rendering. Contributors can propose specification and documentation changes in one repository, use GitHub issues for design discussion, and send patches for review. Consumers who only need the resulting definitions can normally use the published site instead of operating this toolchain. The decision should therefore follow from the need to define or maintain IPLD itself, not from a desire for a general-purpose static site generator.

## Maintenance Signals, Licensing, and Upgrade Work

The repository is not archived and received its last push on 2026-10-02, so the available maintenance signal is recent. There are no GitHub releases, which means dependency changes are communicated through repository files rather than release entries. The visible version is `1.0.0`, but `package.json` also sets `private` to `true`. That version should not be interpreted as evidence of a stable public release cadence for IPLD itself.

Dependency upgrades can affect both site generation and local verification. The listed Eleventy stack includes `@11ty/eleventy` `^3.1.6`, `@11ty/eleventy-navigation` `^1.0.5`, and several Markdown and Eleventy plugins. The hyperlink checker is pinned separately to release `0.1.15` through download URLs. A Node.js upgrade can therefore coincide with plugin changes, while a site change can expose an incompatibility in the downloaded checker. The repository provides cleanup and build commands, but no documented dependency update policy or migration procedure.

The README states the SPDX identifier `Apache-2.0 OR MIT`. The repository also contains `LICENSE-APACHE` and `LICENSE-MIT`, alongside a top-level `LICENSE`. This indicates dual licensing as documented by the project, but it does not replace checking the exact files and any per-directory notices before reuse. Contributors should preserve required notices and follow the terms that apply to the material they copy or distribute.

## Conclusion

Adopt this repository if you intend to read, correct, or publish IPLD specifications and documentation, or if you need to preview changes to the IPLD website. Do not treat it as a library for storing or resolving content-addressed data in an application. Before changing specifications, verify the affected design documents, schema files, and links with `npm test`; before redistributing licensed text or code, inspect `LICENSE`, `LICENSE-APACHE`, and `LICENSE-MIT` for the exact terms and attribution obligations.

## FAQ

### What is the ipld/ipld repository used for?

It is the entry point for IPLD documentation, specifications, the website, and design work. The published website is available at `https://ipld.io/`.

### How do I build the IPLD documentation website locally?

With Node.js 16 or newer, run `npm install` and then `npm run build`. The build script runs Eleventy from the `.site` directory.

### Does ipld/ipld provide a library for storing and resolving IPLD data?

No. The repository describes itself as the project entry point for documentation, specifications, the website, and design work. Its package is private and its scripts concern building and checking the site.

## Sources

- [ipld/ipld on GitHub](https://github.com/ipld/ipld)
- [Issues](https://github.com/ipld/ipld/issues)
- [Project website](https://ipld.io/)
- [README](https://github.com/ipld/ipld/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ipld-ipld