Skip to content

Self hosting reader

Reader is a web application designed to present scholarly and structured documents (e.g., journal articles, academic monographs, research outputs) in a highly readable, accessible, and responsive format.

It complements the SciFlow editor and publishing pipeline, acting as the primary consumption surface for users accessing structured content in digital formats.

A working example of the Reader is available on SciFlow OJS plugin system and in the demo within these docs.

Quick Start

Adding Reader to your web page is the most simplest way to make it available for your documents.

If you use HTML (directly or via a template management engine), you can include Reader by adding this snippet of code to your page.

<script
  id="reader"
  async
  src="https://cdn.sciflow.net/reader/1.0.0-beta/js/main.js"
></script>

This snippet specifies the version 1.0.0-beta and available for usage with

<sfo-reader></sfo-reader>

Reader uses the Google Material fonts for icons. This should also be added to your html.

<link
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined"
  rel="stylesheet"
/>

Full example

<!doctype html>
<html lang="en">
  <head>
    ...
    <script
      id="reader"
      async
      src="https://cdn.sciflow.net/reader/1.0.0-beta/js/main.js"
    ></script>
    <link
      href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined"
      rel="stylesheet"
    />
  </head>
  <body>
    <sfo-reader> </sfo-reader>
    <script>
      customElements.whenDefined("sfo-reader").then(() => {
        const sfoReader = document.querySelector("sfo-reader");
        sfoReader.source = "https://example.com/replace-with-your-source";
      });
    </script>
  </body>
</html>

Loading Documents

The Reader can load documents in two ways:

1. URL Query Parameter

The simplest method is to provide the document URL using the ?url= query parameter:

yoursite.com/reader?url=https://example.com/document.zip

The Reader will automatically detect and load the document from the specified URL.

2. Programmatically

Load documents programmatically via the source property:

<sfo-reader id="reader"></sfo-reader>

<script>
  customElements.whenDefined('sfo-reader').then(() => {
    const sfoReader = document.querySelector('sfo-reader');
    sfoReader.source = 'https://example.com/replace-with-your-source';
  });
</script>

Documents must be provided as ZIP files containing SFO-compatible document snapshots. You can download them from the editor by clicking "Reader Snapshot (ZIP)" in the advanced export menu.

The Reader fetches the ZIP from the browser. If the ZIP is on a different host from the page that embeds the Reader, that host must allow cross-origin requests (CORS) from your Reader's origin, or the download fails.

Reader in a self-hosted SFO

A self-hosted SFO instance serves its own copy of the Reader at /export/reader/. It takes the same ?url= parameter:

https://your-sfo-host/export/reader/?url=https://example.com/document.zip

For templates that offer the Reader, the "Reader" button in the export menu opens the current document there.

Available Themes

Currently implemented themes:

  • Default (Blue: #0B6B9F)
  • Maroon (#800000)
  • Green (#5aa451)

The theme is set in the template, in its kind: Reader configuration block:

kind: Reader
spec:
  theme:
    color: maroon # "" (default), maroon or green
    mode: dark # light, dark or system_preference (default)

The setting travels with the Reader snapshot, and the Reader applies it when it opens the document.

Theme files are located in packages/reader/core/src/styles/ in the Reader source.

Configuration

Dependencies

Reader uses CDN-hosted libraries for styling and optional functionality. Organizations with security policies restricting external CDN usage should consider self-hosting these dependencies.

Core Dependency

Google Material Fonts

Google Material Fonts is used for typography and icons within the Reader application. For more details, it can be found in the Google Material Symbols Guide

<!-- Google Material Icons -->
<link
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined"
  rel="stylesheet"
/>

<!-- Roboto Font -->
<link
  href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500&display=swap"
  rel="stylesheet"
/>

Optional Dependencies

MathJax (mathematical equations)
  • Only required for documents containing mathematical expressions
  • Without MathJax, math expressions will display as raw LaTeX code
  • Can be omitted if your documents don't contain mathematical notation
  • Setup instructions: MathJax Getting Started Guide
highlight.js (for code syntax highlighting)
  • Only required for documents with code blocks requiring syntax highlighting
  • Without highlight.js, code blocks will display as plain text
  • Can be omitted if your documents don't contain code examples
  • Setup instructions: highlight.js Usage Guide

Self-Hosting Alternative

For environments requiring CDN independence, download and host these libraries locally, then update HTML references to point to your local files.

Configuration Guides