issues/completed/5-014-implement-similarity-link-navigation.md

Issue 014: Implement Simple "Similar" and "Unique" Link Navigation

Current Behavior

  • No simple navigation links between similarity and diversity exploration modes
  • Users cannot easily access the 13,680+ generated pages
  • Missing basic "similar" and "unique" links as shown in reference diagram

Intended Behavior

  • Add simple "similar" and "unique" text links on each poem in chronological index
  • Links point to respective similarity and diversity pages for that poem
  • Flat HTML format matching compiled.txt 80-character width
  • No complex dual system interface - just basic text links

Suggested Implementation Steps

  1. Add Navigation Links: Insert "similar" and "unique" links next to each poem in chronological index
  2. Link Target Generation: Ensure links point to correct similarity/diversity pages
  3. Format Compliance: Match reference diagram's simple text link format
  4. No Complex Systems: Remove any elaborate navigation interfaces
  5. 80-Character Format: Maintain compiled.txt width and center alignment

Technical Requirements

Simple Link Integration

-- {{{ function add_simple_navigation_links_to_chronological_index
function add_simple_navigation_links_to_chronological_index(poems_data, output_dir)
    -- Generate chronological index with "similar" and "unique" links
    local sorted_poems = {}
    for poem_id, poem_data in pairs(poems_data.poems) do
        table.insert(sorted_poems, {id = poem_id, poem = poem_data})
    end
    table.sort(sorted_poems, function(a, b) return a.id < b.id end)
    
    local template = [[<!DOCTYPE html>
<html>
<head>
<title>Poetry Collection</title>
</head>
<body>
<center>
<h1>Poetry Collection</h1>
<p>All poems in chronological order</p>

<pre>
%s
</pre>

</center>
</body>
</html>]]
    
    local content = ""
    for _, poem_info in ipairs(sorted_poems) do
        local poem_id = poem_info.id
        local poem = poem_info.poem
        
        -- Add 80-character divider
        content = content .. string.rep("-", 80) .. "\n\n"
        
        -- Add poem content (wrapped to 80 characters)
        content = content .. wrap_text_80_chars(poem.content or "") .. "\n"
        
        -- Add simple "similar" and "unique" navigation links
        content = content .. string.format(
            "<a href='similar/%03d.html'>similar</a> <a href='unique/%03d.html'>unique</a>\n\n",
            poem_id, poem_id)
    end
    
    local final_html = string.format(template, content)
    local output_file = output_dir .. "/poems/index.html"
    os.execute("mkdir -p " .. output_dir .. "/poems")
    
    return utils.write_file(output_file, final_html) and output_file or nil
end
-- }}}

Text Wrapping Utility

-- {{{ function wrap_text_80_chars
function wrap_text_80_chars(text)
    local lines = {}
    local words = {}
    
    for word in text:gmatch("%S+") do
        table.insert(words, word)
    end
    
    local current_line = ""
    for _, word in ipairs(words) do
        if #current_line == 0 then
            current_line = word
        elseif #current_line + 1 + #word <= 80 then
            current_line = current_line .. " " .. word
        else
            table.insert(lines, current_line)
            current_line = word
        end
    end
    
    if #current_line > 0 then
        table.insert(lines, current_line)
    end
    
    return table.concat(lines, "\n")
end
-- }}}

Link Validation

-- {{{ function validate_navigation_link_targets
function validate_navigation_link_targets(poems_data, output_dir)
    local validation_results = {
        total_poems = 0,
        missing_similar_pages = {},
        missing_unique_pages = {},
        valid_links = 0
    }
    
    for poem_id, poem_data in pairs(poems_data.poems) do
        validation_results.total_poems = validation_results.total_poems + 1
        
        -- Check if similar page exists
        local similar_page = string.format("%s/similar/%03d.html", output_dir, poem_id)
        if not file_exists(similar_page) then
            table.insert(validation_results.missing_similar_pages, poem_id)
        end
        
        -- Check if unique page exists
        local unique_page = string.format("%s/unique/%03d.html", output_dir, poem_id)
        if not file_exists(unique_page) then
            table.insert(validation_results.missing_unique_pages, poem_id)
        end
        
        -- Count valid links
        if file_exists(similar_page) and file_exists(unique_page) then
            validation_results.valid_links = validation_results.valid_links + 1
        end
    end
    
    return validation_results
end
-- }}}

Quality Assurance Criteria

  • All poems in chronological index have "similar" and "unique" text links
  • Links point to correct similarity and diversity pages (13,680+ total pages)
  • Flat HTML format matching compiled.txt 80-character width
  • Simple text links without complex styling or elaborate interfaces
  • Center-aligned content matching reference diagram format

Success Metrics

  • Simple Navigation: Every poem has basic "similar" and "unique" text links
  • Coverage: All 13,680+ pages accessible via simple navigation
  • Format Compliance: Links match reference diagram format exactly
  • Accessibility: Works as pure HTML without CSS or JavaScript
  • Integration: Links integrate smoothly into chronological index

Dependencies

  • Issue 008b: Mass page generation system (provides 13,680+ target pages)
  • Issue 007: Removal of complex systems (eliminates conflicting navigation)
  • Chronological index generation: Integration point for simple links

Related Files

  • Format Reference: /notes/HTML-file-format.png - Shows exact "similar" and "unique" link format
  • Compiled Format: /compiled.txt - Source format for 80-character width presentation

ISSUE STATUS: COMPLETED ✅📄

Priority: Medium - Simple navigation links for exploration system

Completed: December 12, 2025 - Simple "similar" and "unique" links fully implemented

🎉 IMPLEMENTATION RESULTS

All Requirements Successfully Implemented:

  1. ✅ Simple Navigation Links: Every poem in chronological index has both "similar" and "unique" text links
  1. ✅ Correct Link Targets: Links properly point to similarity/diversity pages (format: similar/001.html, unique/001.html)
  1. ✅ Flat HTML Format: Matches compiled.txt 80-character width perfectly
  1. ✅ No Complex Systems: Simple text links without elaborate interfaces
  1. ✅ Format Compliance: Exactly matches reference diagram specifications

✅ Verification from Current Output:

<a href='similar/001.html'>similar</a> <a href='unique/001.html'>unique</a>
  • Navigation coverage: All 6,860 poems have both "similar" and "unique" links
  • Format compliance: Perfect 80-character width with center alignment
  • Integration: Seamlessly integrated into chronological index
  • Accessibility: Pure HTML works without CSS or JavaScript

Implementation Method: Delivered through generate_chronological_index_with_navigation() function in flat-html-generator.lua (same as Issue 007 implementation).

Previous Requirements (Now Implemented)

  • No simple navigation links between similarity and diversity exploration modes → ✅ IMPLEMENTED
  • Users cannot easily access the 13,680+ generated pages → ✅ FIXED (simple links provide access)
  • Missing basic "similar" and "unique" links as shown in reference diagram → ✅ IMPLEMENTED