Publish open textbooks, course readers, student projects, and other OER publications on the web, without building from scratch. This package, combined with the Grav Premium Helios theme, provides a web-first reading platform built on Grav CMS (an open-source, flat-file CMS with no database required and a built-in Admin panel), with content you fully control.

Who This Is For

Helios Open Reader is a web-first publishing platform: a place to openly share open textbooks, course readers, student projects, and other OER that you keep and control. It is not a learning management system and does not include enrollment, grade tracking, or student progress features.

It is well suited for educators and authors who want full control over their content, structure, and hosting, including:

• Individual educators wanting a clean, open web reader for course materials or an open textbook
• Authors publishing OER with CC licensing and open-authoring workflows
• Teams hosting shared readings, lab manuals, or module collections
• Instructors hosting student projects or a collaboratively maintained living publication updated each term

Content pages are written in Markdown, with optional shortcodes for embedding and callout blocks. For zero-setup publishing directly from GitHub or Codeberg without a Web server, Docsify-This is a natural companion.

Why Helios Open Reader

Helios Open Reader gives you a modern, open, and fully controlled web reading experience that works alone or embedded in any LMS – a dedicated home for open textbooks, course readers, and student projects that you control completely.

• Ready in minutes – a complete, pre-configured package with demo content included
• Structured – supports sections with sub-pages, auto-detected from folder naming, with a configurable section label (Chapter, Project, Unit, Module, or any custom term)
• Callout blocks – Learning Objectives, Key Takeaways, Examples, Exercises, Definitions, Reflections, and Case Studies, all without coding
• Keep My Place – readers can return to where they left off — a feature most open textbook platforms don't offer
• Reading progress – accessible progress indicator shows current page position (e.g. Page 4 of 22)
• LMS-ready – embed any page cleanly in Canvas, Moodle, or Brightspace with a single URL parameter — no LTI configuration required
• No build pipeline – edit in the browser and changes go live immediately; nothing to install locally
• CMS and Git together – browser-based editing and automatic Git Sync; no need to choose between them
• Content you own – your content lives as portable Markdown files, fully independent of any platform or service
• Bring existing content – the companion Pressbooks Converter (Beta) turns a Pressbooks export into a ready-to-use Open Reader in minutes
• Support open source – your Grav Premium Helios theme purchase directly supports ongoing development of the open-source Grav CMS

Features

Helios Open Reader provides a ready-built site for open educational content – open textbooks, readers, and student projects – using portable Markdown files you fully control. Highlights include a configurable sections structure, multi-publication support, a full set of callout blocks, Keep My Place navigation, and optional Git Sync for open collaborative authoring.

Reader Structure

• Sections structure – top-level folders named section-N are auto-detected as sections and render as cards on the reader home
• Multi-publication – group multiple publications (books, guides, essays, reports) under a single readers home page; each publication has its own cover image, metadata, and section card grid; publication folders using section-list.md at root level are auto-detected; the sidebar shows links back to the readers list and the current publication home; by default chapters list directly in the sidebar — add nested_section_nav: true to a publication's section-list.md to show a collapsible section home parent instead
• Optional parts grouping – rename section folders to part-N-section-M (e.g. part-1-section-1, part-2-section-1) to group sections into parts; part headings appear automatically on the reader home, and Prev/Next navigation and reading progress are scoped per part
• Section N header – section pages automatically display their section number and label in the page header; inherits correctly for all sub-pages within a section. The label is configurable (e.g. Chapter, Project, Unit, Module) via Admin → Pages → Reader Home → Section Label
• Section sub-pages – sections can contain any number of sub-pages, all shown in the sidebar and navigable with Prev/Next controls
• Reader home page with cover image, title, subtitle, authors, edition, and CC license badge

Callout Blocks

• Learning Objectives –

  Learning Objectives

  ...
  (green); also available as frontmatter (learning_objectives:) for automatic rendering at the top of a section landing page
• Key Takeaways –

  Key Takeaways

  ...
  (blue)
• Example –

  Example

  ...
  (purple)
• Exercise –

  Interactive Activity

  ...
  (amber)
• Definition –

  Definition

  ...
  (blue)
• Reflection –

  Reflection

  ...
  (green)
• Case Study –

  Case Study

  ...
  (red)
• Announcement –

  Announcement

  ...
  (purple by default; configurable type)
• Project Brief –

  Project Brief

  ...
  (amber); frames the assignment or challenge prompt
• Feedback Requested –

  Feedback Requested

  ...
  (purple); flags content awaiting review — useful in student projects and draft OER alike
• Process Note –

  Process Note

  ...
  (blue); documents iterations, decisions, or pivots during a project
• All callouts accept an optional title="..." parameter and support Markdown content
• Five built-in GitHub-style callouts: > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION]

Navigation & Reading Experience

• Keep My Place – records the last section page visited in localStorage; a dismissable "Continue reading" strip appears on the publication home page on return, linking directly to the last section read
• Reading progress indicator – shows current page position (e.g. Page 4 of 22) with an accessible progress bar above the Prev/Next navigation on section pages
• Prev/Next navigation – configurable position: top, bottom, or both
• TOC scroll spy – active heading highlighted in the Table of Contents as the reader scrolls
• Start button – on the reader home; links directly to the first section. Button text is configurable (e.g. Start Reading, Browse Projects, View Guides)
• Search across the full reader via the simplesearch plugin

Embedding & Shortcodes

• Embed rich content with built-in shortcodes: iFrames, Google Slides, PDFs, H5P, and Embedly cards, with responsive 16:9 layout and automatic dark/light theme detection
• TOC position override: append ?toc_position=hidden|left|right to any page URL to override the Table of Contents position per request, without changing page frontmatter
• Git link visibility: append ?edit_link=false (or ?hidegitlink=true) to any page URL to hide the "Edit this Page" link per request

LMS Embedding

Append ?embedded=true to any page URL to display only the page content – no sidebar, header, or pagination. Designed for embedding Helios Open Reader pages in an LMS iframe (Canvas, Moodle, Brightspace, etc.).

• All internal links automatically carry the ?embedded=true parameter forward, so navigating between pages stays in embedded mode
• ?chromeless=true is also supported as an alternative parameter name
• Works with HTMX navigation – links in dynamically loaded content are also rewritten
• Combine with ?toc_position=hidden to also hide the Table of Contents, useful for narrow iframe embeds
• Combine with ?toc_position=left or ?toc_position=right to reposition the Table of Contents, useful for working with surrounding LMS navigation elements
• Combine with ?edit_link=false (or ?hidegitlink=true) to hide the "Edit this Page" link on a per-page basis

Example iframe:

<iframe src="https://yoursite.com/section-1/introduction?embedded=true" width="100%" height="600" style="border:none;"></iframe>

Authoring & Customization

• Git Sync plugin included for syncing reader content with GitHub, Codeberg, or similar Git hosting
• Automatic "Edit this Page" link via the Helios theme, defaulting to View Page Markdown for open access to reader content; optionally configurable to direct editing for contributors with repository access
• OER attribution block – display a CC license statement in the footer, drawn from reader home page frontmatter
• Plain text version link – a "Plain text version" footer link pointing to /llms-full.txt, Grav's native full-content Markdown export, for open access to all reader content in a portable, format-neutral form; useful for ebook generation (e.g. Pandoc), search and indexing tools, and AI-compatible tools. Turning on Serve Per-Publication llms-full.txt gives each reader its own /<publication>/llms-full.txt on multi-publication sites (requires Grav 2.1+); single-publication sites use Sitemap's site-wide file (shown when its "Serve llms-full.txt" setting is enabled)
• Customize CSS and JavaScript via the bundled plugin assets
• Print stylesheet with page break control, absolute link URLs displayed inline, and consistent page margins across browsers

Quick Start

The skeleton is a complete package – Grav CMS, the Helios Open Reader plugin, and demo content are all included; the Grav Premium Helios theme requires a separate license. The home page is a readers list with two demo publications.

Pre-flight Checklist

1. Confirm your web server meets Grav's requirements (PHP 8.0 or higher)
2. Have your web server login credentials ready (username and password)

Installation Steps

1. Download the Grav Helios Open Reader Skeleton package
2. Unzip the package onto your desktop
3. Copy the entire Grav Helios Open Reader folder to your web server (e.g. into public_html/ or a subfolder within it)
4. Open your browser and go to your site's URL (e.g. https://yoursite.com/grav-open-reader)
5. Create your site administrator account when prompted
6. Enter your Helios and SVG Icons license keys (or import an existing license file), then install and activate the theme
7. You're done! – press the preview icon in the Admin Panel to view your site

Reader Setup

All reader content lives within user/pages/. A publication is a titled reader with its own home page, authors, sections, and optional parts.

The skeleton ships pre-configured in multi-publication mode with two demo publications.

Default Setup (Multi-Publication)

user/pages/
├── 00.readers/              # Readers home
│   └── reader-list.md
├── 01.open-reader-guide/         # Publication 1 — Grav Helios Open Reader
│   ├── section-list.md           # Publication home
│   ├── 01.section-1/             # Section 1 (with sub-pages)
│   └── ...
├── 02.open-education-essentials/ # Publication 2 — Open Education Essentials
│   ├── section-list.md
│   └── ...
└── readme/

The readers home auto-detects all publication folders at root level and displays them as cards. Section names in the sidebar are drawn from each section page's title field — no versioning.labels configuration is needed.

To add a new publication, create a numbered folder at root level with a section-list.md — set at minimum a title — and your section folders inside.

To hide a publication from the list while keeping its URL accessible, set visible: false in the publication's section-list.md frontmatter.

Readers List Settings (reader-list.md)

Global settings for section label, Prev/Next position, and OER attribution are set here and apply to all publications; individual publications can override them in their own section-list.md.

Page content in reader-list.md appears above the reader cards by default. Use === as a delimiter to also show content below the cards.

Publication Home Settings (section-list.md)

These fields apply when section-list.md is used as the publication home (recommended). These fields are set in the publication's section-list.md.

Showing and Hiding Publications and Sections

In the Admin panel, open the publication or section folder and set Published to Yes to show or No to hide it. Unpublished publications and sections are also excluded from search results and the sidebar.

Once you have set up your own content, you can safely delete any unused demo publications or sections from user/pages/ via the Admin panel or FTP.

Adding a New Section

To add a section inside a publication, copy an existing section folder (e.g. 01.open-reader-guide/01.section-1/) into the same publication's folder via FTP or the Admin panel. Ensure the folder name follows the section-N convention, then set Published to Yes in the Admin panel to make it visible.

Single-Publication Alternative

If you only need a single publication and prefer a simpler root-level folder structure, you can convert the skeleton to single-publication mode:

1. Remove the 00.readers/ folder
2. Move your publication folder's contents (section-list.md and section folders) to root level
3. Update home.alias in user/config/system.yaml to point to your reader home (e.g. /open-reader-guide)

user/pages/
├── 00.my-publication/    # Reader home page
│   └── section-list.md
├── 01.section-1/
├── 02.section-2/
├── 03.section-3/
└── readme/

Grouping Sections into Parts

Parts grouping applies in single-publication mode. To group sections into parts on the reader home page, use the part-N-section-M folder naming pattern instead of section-N:

user/pages/
├── 00.my-publication/
├── 01.part-1-section-1/    # Part 1, Section 1
├── 02.part-1-section-2/    # Part 1, Section 2
├── 03.part-2-section-1/    # Part 2, Section 1
├── 04.part-2-section-2/    # Part 2, Section 2
└── readme/

Parts are detected automatically — no additional configuration required. Part headings ("Part 1", "Part 2") appear above each group of section cards on the reader home page, Prev/Next navigation stops at part boundaries, and the reading progress indicator counts pages within the current part only.

To use custom part titles instead of the auto-generated "Part 1", "Part 2" labels, add a parts block to section-list.md:

parts:
  - id: part-1
    label: 'Foundations of Open Education'
  - id: part-2
    label: 'Applying Open Practices'

Reader Home Settings

The section-list.md frontmatter controls the publication identity and card layout. In single-publication mode it is the reader home; in multi-publication mode it is the publication home inside each publication folder. These fields can be set in the Admin Panel by opening the relevant page.

Page content written in section-list.md appears above the cards by default. To also display content below the cards, add === on its own line as a delimiter:

This text appears above the section cards.

===

This text appears below the section cards.

Reader Section Settings

The section.md frontmatter controls each section's landing page and card appearance.

Individual content pages within a section (section-page.md) have no custom frontmatter — add content directly in the editor.

Label Customization

Reader Title

The title displayed in the browser tab and header comes from the title field in section-list.md. Edit it via Admin → Pages, or directly in the section-list.md file in the relevant publication folder.

Section Label

The label used for sections throughout the reader (in page headers, cards, and the sidebar) can be set via Admin → Pages → Reader Home → Section Label. Leave it empty to use the language default (Section in English, Chapitre in French). Examples: Chapter, Project, Unit, Module.

For multi-language sites, the per-language default is set via SECTION_LABEL in user/plugins/helios-open-reader/languages.yaml. English and French are included:

en:
  PLUGIN_HELIOS_OPEN_READER:
    SECTION_LABEL: Section
    SECTION_LATEST_LABEL: latest

fr:
  PLUGIN_HELIOS_OPEN_READER:
    SECTION_LABEL: Chapitre
    SECTION_LATEST_LABEL: dernière

Part Label

When sections are grouped into parts using the part-N-section-M folder naming pattern, the part heading label (default: Part) can be customized via Admin → Pages → Reader Home → Part Label. Leave it empty to use the default. Examples: Theme, Project.

To use custom titles for individual parts instead of the auto-generated "Part 1", "Part 2" labels, add a parts block to section-list.md frontmatter:

parts:
  - id: part-1
    label: 'Foundations of Open Education'
  - id: part-2
    label: 'Applying Open Practices'

Section Names

The individual section name shown in the sidebar, the section dropdown (when enabled), and as the middle segment of the browser tab title (Page Title | Reader Title | Site Title) comes from the versioning.labels setting in the Helios Theme config. These can be edited via Admin → Themes → Helios → Versioning tab → Version Labels, or directly in user/config/themes/helios.yaml:

versioning:
  labels:
    section-1: 'What is Open Education?'
    section-2: 'Tools for Open Course Design'
    section-3: 'Getting Started with Open Authoring'

Browser Tab Title

The browser tab title is automatically formatted as:

Page Title | Reader Title | Site Title

The Reader Title is drawn from the reader home page title. The Site Title comes from site.title in user/config/site.yaml. Set the Site Title to your institution or author name – it serves as the top-level identifier in the browser tab.

Git Sync & Open Editing

The skeleton includes the Git Sync plugin, which keeps your site content automatically in sync with a GitHub or Codeberg repository. This enables a full open-authoring workflow:

• Content editors can work directly in the Grav Admin or commit changes via Git
• The Helios Theme's "Edit this Page" option defaults to a 'View Page Markdown' link on each page, taking readers directly to the Markdown source file in your repository (configurable to link directly to file editing via the Helios Open Reader plugin settings)

If you prefer not to write Markdown directly, the optional Grav Premium Editor Pro provides a visual block editor for editing pages.

Included Plugin: Helios Open Reader

Custom CSS, JavaScript, shortcodes, callout blocks, and Helios-inspired Admin Panel styling for the Helios Open Reader skeleton. If the Helios theme is not installed, the plugin automatically falls back to the Quark or Quark2 theme so the frontend site remains viewable, redirecting to the License Manager page in the Admin panel.

Templates

• reader-list – Readers home template displaying a card grid of all publications (multi-publication mode)
• section-list – Reader home for single-publication mode and publication home in multi-publication mode; displays the reader header, resume reading strip, and section card grid
• section – Section landing page with optional section number, Learning Objectives block, and card metadata (description, icon, image, badge); one per section folder
• section-page – Individual section content page; no custom frontmatter — add content directly in the editor
• default-toc – Content page template with a right-column Table of Contents; set template: default-toc in any page's frontmatter to enable (requires the page-toc plugin, included)

Assets

• helios.css – Theme styling (announcement blockquotes, heading typography, Font Awesome spacing, responsive containers)
• reader.css – Reader-specific styles (callout block spacing, resume reading strip, reading progress indicator, top Prev/Next navigation styling)
• helios.js – Embedly dark/light theme support, Keep My Place localStorage logic, HTMX content-loaded integration
• print.css – Print stylesheet (hides navigation chrome, resets colors for light and dark themes, controls page breaks, displays absolute link URLs, sets consistent page margins)
• admin.css – Helios-inspired Admin Panel styling (conditionally loaded based on the Helios-inspired Admin Styling setting)
• admin.js – Admin panel JavaScript customizations

Shortcodes

All callouts accept an optional title="..." parameter and support Markdown content.

• [objectives]...[/objectives] – Learning Objectives block (green)
• [key-takeaways]...[/key-takeaways] – Key Takeaways block (blue)
• [example]...[/example] – Example block (purple)
• [exercise]...[/exercise] – Exercise block (amber)
• [definition]...[/definition] – Definition block (blue)
• [reflection]...[/reflection] – Reflection block (green)
• [case-study]...[/case-study] – Case Study block (red)
• [announcement]...[/announcement] – Announcement notice (purple by default), supports Markdown
• [announcement title="..." type="..."]...[/announcement] – With optional custom title and type (note, tip, important, warning, caution)
• [project-brief]...[/project-brief] – Project Brief block (amber); frames the assignment or challenge prompt
• [feedback-requested]...[/feedback-requested] – Feedback Requested block (purple); flags content awaiting review — useful in student projects and draft OER alike
• [process-note]...[/process-note] – Process Note block (blue); documents iterations, decisions, or pivots during a project
• [excerpt]...[/excerpt] – For long multi-paragraph quoted passages; renders with a subtler grey left border and italic text than the standard Markdown blockquote, closer to how long quotations appear in print
• [iframe url="..."] – Responsive iframe embed, 16:9 by default
• [googleslides url="..."] – Responsive Google Slides embed, 16:9 by default
• [pdf url="..."] – PDF viewer via Google Docs, 16:9 by default
• [pdf url="..." ratio="portrait"] – PDF viewer at portrait ratio (letter/A4)
• [h5p url="..."] – H5P interactive content via full embed URL
• [h5p id="..."] – H5P interactive content via Content ID (requires H5P Content Embed Source URL to be set in plugin settings)
• [embedly url="..."] – Embedly card with dark mode support
• [linkpreviewcard url="..."] – Self-hosted link preview card (image, title, description) scraped directly from the page; an alternative to [embedly] that doesn't rely on the embed.ly service

Plugin Settings

The following settings are available in the Admin panel under Plugins → Helios Open Reader:

Note: The Helios-inspired Admin Panel 1.7 colour scheme (zinc nav, accessible blue links, muted purple accents) is pre-configured in this skeleton.

Requirements

• PHP >= 8.0
• Grav CMS >= 1.7.0
• Grav Premium Helios Theme – one license per site (Standard or Team)

Bring Your Pressbooks Content With You

The companion Pressbooks Converter (Beta) transforms a Pressbooks XHTML export into a complete Open Reader in minutes – sections, chapters, learning objectives, H5P activity links, cover image, license, and OER attribution all carried across automatically. Because Pressbooks exports follow a single, consistent format, conversions are typically a close, faithful match to the original book. Upload your export and browse the resulting Markdown files directly – no Grav or Helios installation needed to see what carries over.

Support

Contact and Support

• Follow @hibbittsdesign@mastodon.social on Mastodon for updates
• 👩🏻‍💻🧑🏻‍💻 Join the Grav Discord and often find me there
• Add a ⭐️ star on GitHub to the Helios Open Reader project repository
• For bugs or feature requests, open an issue on GitHub

Professional Services

By leveraging his extensive UX design expertise and systems-oriented approach, Paul helps teams and individuals utilize open content in education and publication settings. Professional services include user experience and workflow consulting, premium support subscriptions, workshops, and custom development. Interested? Send a note to paul@hibbittsdesign.org.

License

MIT – Hibbitts Design