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 = "http: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 = 'http: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.

Available Themes

Currently implemented themes:

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

Theme files are located in libs/reader/src/styles/.

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