WikiJS Builder Output Issues: Exploration & Planning Log

Overview

This document tracks the investigation and planned resolution of issues found in the WikiJS builder output, as listed in .taskmaster/tasks/wikijs.md. Each issue is mapped to its likely cause, affected files/modules, and a proposed fix. This log will be updated as work progresses.

Issue-by-Issue Analysis

1. output/markdown-wikijs is missing index.md file

• Likely Cause: Builder not generating index.md or incorrect output path.
• Affected Module: MarkdownBuilder (likely in lib/codexis/builders/markdown_builder.ex)
• Proposed Fix:
  • Audit builder logic for index file generation.
  • Ensure index.md is created and written to the correct output directory using PathBuilder.
  • Add/verify test for index file presence.

2. output/markdown-wikijs is missing scan.md file

• Likely Cause: Scan file not included in build process or missing source.
• Affected Module: MarkdownBuilder
• Proposed Fix:
  • Check if scan.md is part of the input or should be generated.
  • Update builder to include or generate scan.md as needed.

3–5. Missing cover images, book images, and scans images in output/markdown-wikijs/content/

• Likely Cause: Asset copying logic incomplete or incorrect path handling.
• Affected Module: MarkdownBuilder, asset management utilities
• Proposed Fix:
  • Review asset discovery and copy logic.
  • Ensure all images (cover, book, scans) are found and copied using PathBuilder for all path operations.
  • Add/verify tests for asset presence in output.

6. index.md is missing title and description in the frontmatter

• Likely Cause: Frontmatter generation missing required fields.
• Affected Module: MarkdownBuilder
• Proposed Fix:
  • Update frontmatter template to include title and description.
  • Add/verify test for frontmatter completeness.

7–8. Content mistranslations (missing spaces)

• Likely Cause: Source parsing or string formatting bug.
• Affected Module: Content parsing/formatting logic in MarkdownBuilder
• Proposed Fix:
  • Identify where string concatenation or parsing is dropping spaces.
  • Add/verify test for correct content formatting.

9–12. Content layout and formatting issues (Contents layout, item links, Foreword formatting, missing spaces in chapter titles)

• Likely Cause: Markdown rendering or template logic errors.
• Affected Module: MarkdownBuilder, templates
• Proposed Fix:
  • Review and fix markdown template logic for contents and links.
  • Ensure correct formatting for Foreword and chapter titles.
  • Add/verify tests for layout and link correctness.

13–14. Code listing format and TODO item formatting

• Likely Cause: Code block rendering or markdown syntax error.
• Affected Module: Markdown rendering logic
• Proposed Fix:
  • Update code block and TODO item rendering logic.
  • Add/verify tests for code and TODO formatting.

15–17. Section 2.1: Missing space, equation not rendered, equation ref link not working

• Likely Cause: Parsing/rendering bug for equations and references.
• Affected Module: Equation and reference handling in MarkdownBuilder
• Proposed Fix:
  • Debug equation and reference rendering logic.
  • Add/verify tests for equations and reference links.

18. Section 2.2: Image is missing

• Likely Cause: Asset not copied or referenced correctly.
• Affected Module: Asset management in MarkdownBuilder
• Proposed Fix:
  • Ensure image is present in source and copied to output.
  • Add/verify test for image presence.

19. Table 1: Formatting issues

• Likely Cause: Table rendering logic error.
• Affected Module: Markdown table rendering
• Proposed Fix:
  • Fix table rendering logic.
  • Add/verify test for table formatting.

20. Missing section of links to epub, PDF, and docx versions

• Likely Cause: Builder not generating or including links to other formats.
• Affected Module: Output summary/footer logic
• Proposed Fix:
  • Update builder to append links to other formats in the output.
  • Add/verify test for presence of links.

General Recommendations

• Use PathBuilder for all path operations to ensure consistency and compliance with project rules.
• Add or update tests for each fix, using Patch for mocking in Elixir tests.
• Document any new patterns or rules discovered during implementation.

Next Steps

1. Prioritize issues (start with missing files/assets, then formatting/content issues).
2. Begin implementation and update this log with progress and findings.
3. Mark resolved issues and document any new issues discovered during the process.