Help

Provides Markdown help files that integrate into the UI

Technology

The help module provides integrated contextual help for Project Forge applications. It enables developers to embed Markdown-based documentation directly into their applications, with automatic help links and modal displays. When available for a page, a help icon will be included in the UI, no JavaScript required.

Overview

This module provides:

Contextual Help: Automatic help links based on controller action keys
Markdown Integration: Rich HTML rendering of Markdown documentation
Modal Display: Non-intrusive help content in overlay modals
Customizable Content: Support for headers, footers, and per-page content
Progressive Enhancement: Works with or without JavaScript

Key Features

Automatic Help Links

Help links automatically appear in navigation when corresponding help files exist
Links are keyed to controller action names for contextual relevance
Modal display keeps users in context while providing assistance

Markdown Processing

Full Markdown syntax support with HTML rendering
Automatic title extraction from first header
Fallback to page title when no header is present
Support for embedded images, links, and formatting

Flexible Content Organization

Per-page help files matched to controller keys
Global header and footer content via _header.md and _footer.md
Template-based generation with project data interpolation

Usage

Controller Integration

Each controller action can automatically display help by matching the action key to a help file:

1
2
3
4
5
6
func HomeAction(w http.ResponseWriter, r *http.Request) {
    controller.Act("home", w, r, func(as *app.State, ps *cutil.PageState) (string, error) {
        // If help/home.md exists, a help link will appear in navigation
        return controller.Render(r, as, page, ps)
    })
}

In this case, it would attempt to read help/home.md and show an icon in the header of the UI.

Help File Structure

Help files are organized in the help/ directory:

help/
├── home.md         # Help for "home" action key
├── about.md        # Help for "about" action key  
├── _header.md      # Optional global header content
└── _footer.md      # Optional global footer content

Content Templates

Help files support Go template syntax with project data:

1
2
3
# Welcome to {{{ .Name }}}

This application was generated by Project Forge and includes...

Conditional Generation

Files prefixed with ! in the header are disabled by default:

1
2
3
# !About Page

Remove the `!` prefix to enable this help file.

Best Practices

Help Content Organization

Use descriptive, action-oriented help file names
Keep help content focused and concise
Include examples and common use cases
Provide links to more detailed documentation when appropriate

Markdown Guidelines

Use clear hierarchical headers (H1, H2, H3)
Include code examples in fenced blocks
Use lists and tables for structured information
Add images sparingly and optimize for quick loading

User Experience

Write help content from the user’s perspective
Focus on completing tasks rather than describing features
Use consistent terminology throughout the application
Test help content with actual users when possible

Source Code

Repository: https://github.com/kyleu/projectforge/tree/main/module/help
License: CC0 (Public Domain)
Author: Kyle U (kyle@kyleu.com)