The main reason we haven’t had visible connections between web pages until now is that the Web doesn’t have a default web page format. We need a standardized page type—one that supports only minimal styling and no scripts. It has to be based on HTML (so we can reuse existing content), but it also needs a different name so it’s not confused with regular HTML pages.
That’s what HDOC — Hypertext Document — is. It’s a new kind of web page.
To use visible connections, your main document must be an HDOC. There are two versions: standalone HDOC and embedded HDOC.
Scenario 1
If you want to create something like:
- a history article connected to maps
- parallel histories (events in different places happening at the same time)
- commentary linked to an original source
…then standalone HDOCs are the right choice.
Just create an HDOC following the format description and publish the file on your website.
Scenario 2
If you run a blog and sometimes want to link to external sources (other pages anywhere on the Web), embedded HDOCs are better.
Your posts will look normal for people who don’t use any special software.
But for people who do have the Visible Connections extension installed, your posts will behave like HDOCs and support floating links.
If you use WordPress, just install the plugin.
A note about publishing standalone files
Until mainstream browsers support HDOCs directly, the main way to view them is through the browser extension.
The problem is that browsers usually download unknown file types instead of displaying their source in the browser. You must avoid that—HDOCs need to stay in the browser so the extension can read them.
There are several ways to make sure HDOCs, CDOCs, and CONDOCs open in the browser:
1. The lazy way
Add a .html extension after the format extension: my_file.hdoc.html. Don’t use .txt. It looks like it works, but it breaks encoding for some characters. The downside of this approach is that it may be confusing because you specify format as HTML while in reality a different format is used in the file.
2. Use rewrite rules
Store your files with a .html extension, but configure your server so that URLs ending in .hdoc (or .cdoc / .condoc) internally serve the .html version.
You can also block direct access to the .hdoc.html file.
For Apache, add this to your .htaccess:
BEGIN Custom Rewrite for .html trick
RewriteEngine On
#1. Block ONLY real external requests for .hdoc.html / .cdoc.html / .condoc.html
# (Internal rewrites are allowed because THE_REQUEST is unchanged)
RewriteCond %{THE_REQUEST} \s/+(.+).(hdoc|cdoc|condoc).html
RewriteRule . - [R=404,L]
#2. Internally rewrite .hdoc → .hdoc.html only if .html file exists
RewriteCond %{REQUEST_FILENAME}.html -f
RewriteRule ^(.+).(hdoc|cdoc|condoc)$ $1.$2.html [L]
END Custom Rewrite for .html trickIf you use WordPress, add this before the WordPress section.
With this setup, you must always upload files like:
myfile.hdoc.html
my_collage.cdoc.html
connections.condoc.html
But visitors will use URLs like:
https://yoursite.com/myfile.hdoc
Accessing https://yoursite.com/myfile.hdoc.html will return 404 (as intended).
The downside of this approach is that you still have to deal with file names ending in .html, but at least visitors of your website don’t see them.
3. Use WordPress + Static Web Publisher
If you use the Static Web Publisher plugin, create a folder named static-documents inside your public folder.
Any .hdoc, .cdoc, or .condoc placed inside static-documents or any of its subfolders will be accessible at URLs like:
https://yoursite.com/static/myfile.hdocNote the /static/ part.
The downside of this approach is that all documents of the new formats must be in one special folder and the URL for accessing them has to use /static/ suffix.
How to actually create visible connections
I recommend using the LZ Desktop app—especially if you plan to add a lot of floating links. Editing directly in the browser can lead to lost work if something goes wrong with the page.
In many cases, you’ll first publish the document without connections, then create the connections inside the app, export them, and add them to the published document.
See the video for a walkthrough of how to publish connections.
Documentation
You can visit this GitHub repository for the documentation of all the new data types: HDOC, CDOC, CONDOC.
If you want to see how Visible Connections Chrome extension works, its source code is in this repository.
I’ll continue improving these instructions. In the meantime, if something isn’t clear, feel free to email me and I’ll help you publish your first visible connections.