Skip to content

How to: Work with the User Guide

This guide explains how to develop and maintain the SyRF User Guide, which provides end-user documentation for the SyRF platform.

Overview

The User Guide is a Jekyll-based documentation site using the just-the-docs theme. It is:

  • Published at: help.syrf.org.uk
  • Location: /user-guide/ directory in the monorepo
  • Theme: just-the-docs (remote theme)
  • Build: Jekyll static site generator

Prerequisites

  • Docker and docker-compose (for local development)
  • Basic knowledge of Markdown
  • Understanding of Jekyll front matter

Directory Structure

The user guide is organized into logical sections:

user-guide/
├── index.md                    # Home (Getting Started)
├── about.md                    # About CAMARADES & SyRF
├── getting-started/            # Introductory content
├── account/                    # Account management
├── projects/                   # Project management
│   └── membership/            # Nested membership section
├── studies/                    # Study/reference management
├── stages/                     # Screening and annotation
├── data-export/                # Data export guides
│   └── data-dictionary/       # Field definitions
├── whats-new/                  # Release notes
└── figs/                       # Images and screenshots

The just-the-docs theme uses YAML front matter to build the navigation sidebar.

Front Matter Fields

Field Required Description
title Yes Page title in navigation
nav_order Yes Position in sidebar (lower = higher)
parent For children Title of parent page (exact match required)
has_children For parents Set to true if page has children
layout Yes Usually page, use home for landing pages
permalink Optional Custom URL path

Example: Parent Page

---
title: Projects
has_children: true
nav_order: 3
layout: page
---

Example: Child Page

---
title: Create a Project
parent: Projects
has_children: false
nav_order: 2
layout: page
---

Example: Grandchild Page

---
title: Members & Groups
parent: Membership
has_children: false
nav_order: 1
layout: page
---

Note: The parent value must exactly match the title of the parent page.

Adding Content

Creating a New Page

  1. Choose the right directory based on the content topic
  2. Create the markdown file with descriptive name
  3. Add front matter with correct parent/nav_order
  4. Write content using GitHub Flavored Markdown
  5. Add images to figs/ directory

Image References

Images are stored in figs/ and referenced with relative paths.

The pattern depends on the file's depth relative to the figs/ directory:

File Location Image Path
Root level (index.md, about.md) figs/image.png
First-level subdirectory (projects/join.md) ../figs/image.png
Nested subdirectory (projects/membership/inviting.md) ../../figs/image.png

Use standard Markdown image syntax: ![alt text] followed by (<relative-path>).

Use Jekyll's link tag for reliable cross-page linking.

The syntax is: [Link Text] followed by ({{ site.baseurl }}{% link path/to/page.md %}).

Or use relative HTML links: [Link Text] followed by (../path/to/page.html).

Local Development

cd user-guide
docker-compose up

Visit http://localhost:4000 to see the site.

Using Ruby/Bundler

cd user-guide
bundle install
bundle exec jekyll serve

Current Navigation Structure

nav_order Section Description
1 Getting Started Home page and intro content
2 Account Account creation and management
3 Projects Project management (with Membership subsection)
4 Study Management Uploading and managing references
5 Stages Screening and annotation configuration
6 Data Export Exporting project data
7 About Us About CAMARADES and SyRF
8 What's New Release notes and updates

Best Practices

Content Guidelines

  • Write for end users, not developers
  • Use clear, simple language
  • Include screenshots for complex UI interactions
  • Link to related pages where helpful
  • Keep pages focused on a single topic
  • Maintain sequential nav_order within each section
  • Use descriptive but concise page titles
  • Group related content under parent pages
  • Don't nest more than 2 levels deep (parent → child → grandchild)

Image Guidelines

  • Use PNG format for screenshots
  • Include descriptive alt text for accessibility
  • Crop images to show relevant UI elements
  • Use consistent naming: Fig_Section_Description.png

CI/CD Pipeline

The user guide is built and deployed automatically:

  1. Trigger: Push to main branch with changes in user-guide/
  2. Build: Jekyll builds the static site
  3. Package: Docker image created and pushed to GHCR
  4. Deploy: ArgoCD syncs to Kubernetes cluster
  5. Access: Available at help.syrf.org.uk

Troubleshooting

  • Verify parent value exactly matches parent's title
  • Check nav_order is set
  • Ensure front matter delimiters (---) are correct

Images Not Loading

  • Verify correct relative path based on file location
  • Check file exists in figs/ directory
  • Ensure filename case matches exactly (Linux is case-sensitive)

Build Failures

  • Check Jekyll syntax in _config.yml
  • Validate YAML front matter format
  • Review GitHub Actions logs for specific errors