Overview

This update addresses several issues with the documentation system, focusing on role-based access control, path resolution, and template rendering. These improvements ensure that all users can access the documentation they are authorized to view, with proper formatting and navigation.

Date: October 15, 2025
Type: Bug Fix
Priority: High

Issues Fixed

Role-Based Access Control

• Fixed issue where normal users couldn't access documentation marked for their role
• Improved role detection logic to properly handle multiple user roles
• Enhanced special case handling for 'normal' role to ensure any authenticated user can access content
• Added detailed logging to help diagnose access control problems

Path Resolution

• Added support for default paths defined in documentation_config.json
• Implemented a multi-stage path resolution process to find documentation files
• Fixed "page not found" errors for valid documentation pages
• Improved handling of different file types (.md, .tt, etc.)

Template Rendering

• Created a standardized markdown_viewer.tt template for rendering markdown content
• Improved error handling with a dedicated error.tt template
• Enhanced display of documentation metadata (last updated, roles, etc.)
• Fixed styling inconsistencies across different documentation types

Technical Changes

Controller Updates

# Enhanced role-based access control logic
if (lc($role) eq lc($user_role)) {
    $has_role = 1;
    $self->logging->log_with_details($c, 'debug', __FILE__, __LINE__, 'view',
        "Role match: user role $user_role matches required role $role for page $page");
    last;
}
# Special case for normal role - any authenticated user can access normal content
elsif (lc($role) eq 'normal' && $user_role) {
    $has_role = 1;
    $self->logging->log_with_details($c, 'debug', __FILE__, __LINE__, 'view',
        "Normal role access granted to page $page for user with role $user_role");
    last;
}
        

Path Resolution Logic

# Check if there's a default path defined in the documentation_config.json file
if ($config->{default_paths} && $config->{default_paths}{$page}) {
    $default_path = $config->{default_paths}{$page};
    $self->logging->log_with_details($c, 'info', __FILE__, __LINE__, 'view',
        "Found default path for $page: $default_path");
}

# If a default path is defined, try to use it
if ($default_path) {
    my $full_default_path = $c->path_to('root', $default_path);
    
    if (-e $full_default_path) {
        $self->logging->log_with_details($c, 'info', __FILE__, __LINE__, 'view',
            "Using default path for $page: $default_path");
            
        # Determine file type based on extension and render appropriately
        # ...
    }
}
        

User Impact

These changes improve the documentation system in the following ways:

• Normal users can now access all documentation intended for them
• Documentation pages are properly rendered with consistent styling
• Error messages are more informative and helpful
• Navigation between documentation pages is more reliable
• Role-based access control works correctly for all user types

Related Documentation

• Documentation Migration to Template Toolkit
• Documentation Template Toolkit Template