How to create visible connections

You can only use visible connections on web pages published on the Reader's Web. So, first, let's see how you can publish such pages on your website.

Scenario 1

If you use WordPress, just install the plugin.

Also watch this video.

Scenario 2

If you don't have a WordPress website, but 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 you can create a standalone HDOC or an Embedded HDOC.
Just create an HDOC following the format description and publish the file on your website.

In this case the visitors of your website will only see the visible connections, if they have the browser extension installed. So, you'll have to add a note to your pages telling them about the extension. More on that in the video below.

Creating visible connections

Watch this video:

To create visible connections you want to install the extension even if you use the WordPress plugin on your website. Without the extension the process may be a bit awkward.

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 trick

If 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 + Reader's Web Publisher

If you use the Reader's 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.hdoc

Note 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.

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 RW Reader 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.