This repository contains early drafts, proposals, and evolving specifications for the Reader's Web — a new part of the Web where the reader, rather than the publisher, decides what a web page looks like. It is built around stable static data types and visible connections between documents.
This project is inspired by Ted Nelson’s vision of hypertext, ideas that the modern Web never implemented. Early design choices in the 1990s mixed content, presentation, and behavior (HTML + CSS + JavaScript), turning pages into isolated containers and making something as basic as visible connections between documents practically impossible.
The Reader's Web aims to finally introduce true hypertext into the Web ecosystem.
It defines a set of static document types (HDOC, Embedded HDOC, CDOC, Embedded CDOC, CONDOC, Embedded CONDOC, etc.) that:
- don’t support scripts,
- render the same everywhere,
- enable visible connections,
- are self-contained and have no dependencies beyond images and iframes.
These documents form a parallel ecosystem — living alongside today’s HTML pages, and in the case of Embedded HDOCs, CDOCs and CONDOCs, even inside them. Most web pages (blog posts, docs, articles) don’t need custom design or complex interactivity; a stable default format works better. Over time, standalone HDOCs can replace a large portion of the Web.
HTML with CSS and JavaScript remains the right tool for special cases:
- landing pages with heavy design or animation,
- complex applications like social networks, marketplaces, or stores.
But for simple content pages, there should be a default data format.
Currently, Reader's Web document formats support visible connections between pages. As the ecosystem matures, we’ll explore more of Ted Nelson’s concepts: transclusions, richer link types, links with multiple ends, bidirectional links, versioning, micropayments, and more complex relationship graphs (beyond simple one-to-many connections between documents).
Some of these ideas require centralized services. This project’s job is to demonstrate technical feasibility, define the data formats, and build the frontend layer so that when those services appear, they can plug directly into an existing ecosystem.
The following formats are under development:
A static, portable, minimally styled text document format.
Can contain HTML or plain text conent and visible connections to other web pages.
A version of HDOC embedded inside existing HTML pages.
Allows websites to participate in the Reader's Web without having to serve a standalone HDOC from an endpoint different from the URL of the original original HTML page.
A document format for 2D collages. It is based on SVG format and can contain visible connections to any number of other documents.
A version of CDOC embedded inside existing HTML pages. Useful when website provides Reader UI. Embedded CDOC allows you to still use a browser extension in this case and even connect to the CDOC from another document.
A container type that can reference the main document (HDOC, CDOC, or a regular web page with parsing rules), and use visible connections to connect it to any number of other documents.
A version of CDOC embedded inside existing HTML pages. Allows you to view the CONDOC in a browser extension.
HDOCs can include comments stored as a JSON array (inspired by the WordPress comments format, but with small modifications like visible connections to the host page and multiple ID types).
For a full description, see: specs/static-comments.md.
Full draft specifications for each format will be placed in the specs/ directory.
Clients can create HDOCs from ordinary HTML pages using deterministic parsing rules. These rules ensure all clients display the same content and avoid broken links.
For full details, syntax, and examples, see: specs/parsing-rules.md.
/
README.md
GOVERNANCE.md
/specs
cdoc.md
condoc.md
connections.md
embedded-cdoc.md
embedded-condoc.md
embedded-hdoc.md
hdoc.md
parsing-rules.md
static-comments.md
...
/drafts
design-notes.md
- specs/ — finalized or semi-finalized specs (once they exist).
- drafts/ — rough notes, sketches, early proposals.
You may start with drafts and promote them to /specs when they stabilize.
Contributions are welcome in the form of:
- Proposals for syntax or semantics
- Drafts improving document type definitions
- Examples and interoperability tests
- Discussions in issues and pull requests
See GOVERNANCE.md for details on roles and decision-making.
This repository contains two categories of content with separate licenses:
-
Source code (tools, examples, scripts)
Licensed under a permissive open-source license (MIT).
SeeLICENSE-CODE.md. -
Specification documents (HDOC, Embedded HDOC, CDOC, Embedded CDOC, CONDOC, Embedded CONDOC, Parsing Rules, Connections, Static Comments, etc.)
Licensed under Creative Commons Attribution-NoDerivatives 4.0 (CC BY-ND 4.0).
These specifications define document formats and related standards for the Reader's Web project and are not to be modified. SeeLICENSE-SPECS.md.
Unless otherwise noted, each file clearly indicates which license applies.
The Reader's Web specifications are early drafts.
Expect rapid changes as the formats evolve and the ecosystem grows.
The following software projects demonstrate early support for Reader's Web formats. They are not required for implementing or using the specifications.
-
RW Reader (Chrome extension) — adds support for new data formats and visible-connection rendering inside the browser.
-
Reader's Web Publisher (WordPress plugin) — automatically embeds an Embedded HDOC versions on pages and posts. Can serve Reader's Web documents in a special Reader UI. Supports CDOCs and CONDOCs.
-
LZ Desktop (desktop viewer/editor) — standalone app for browsing Reader's Web content and creating new documents with visible connections.
More tools will be added as the ecosystem evolves.
More information about the Reader's Web project, ecosystem updates, and guides can be found at: