Fixes docsite page linking

[ieaves]

Summary by Sourcery

Fix docsite linking issues and improve manpage-to-mdx conversion

Bug Fixes:

• Correct internal See Also links to point to /docs/commands/ramalama/ instead of relative paths
• Fix HISTORY anchor references and remove obsolete TOC entries in converted markdown

Enhancements:

• Map specific .5.md config manpages to custom titles
• Add a clean-generated Makefile target to remove auto-generated MDX files
• Strip HISTORY TOC links during markdown-to-MDX conversion

Documentation:

• Update frontmatter titles for Configuration File and OCI Spec pages

[sourcery-ai]

Reviewer's Guide

This PR refines docsite generation and linking by enhancing title extraction for specific manpages, improving markdown conversion with history footers, standardizing internal ‘See Also’ links to absolute paths, adding a Makefile target to clean generated MDX files, and updating frontmatter for configuration pages.

Class diagram for updated docsite manpage conversion logic

classDiagram
    class convert_manpages {
        +extract_title_and_description(content, filename)
        +convert_markdown_to_mdx(content, filename)
        +convert_link(match)
    }
    extract_title_and_description : - Handles .5.md files with custom titles
    extract_title_and_description : - Fallback for other .5.md files
    convert_markdown_to_mdx : - Removes HISTORY TOC links
    convert_markdown_to_mdx : - Appends history as footer
    convert_link : - Standardizes See Also links to absolute paths

Loading

File-Level Changes

Change	Details	Files
Enhanced title extraction for specific .5.md manpages	Added conditional mapping for ramalama.conf.5.md and ramalama-oci.5.md Retained fallback logic for other .5.md files	docsite/convert_manpages.py
Improved markdown conversion to remove TOC HISTORY links and append history as footer	Strip out '- [HISTORY]' entries during conversion Ensure HISTORY section is appended as a footer block	docsite/convert_manpages.py
Standardized internal 'See Also' links to absolute /docs/commands/ramalama/ path	Updated convert_link to point to '/docs/commands/ramalama/' by default Applied updated links across generated MDX and platform guide docs Adjusted installation doc reference and nav link in docusaurus.config.ts	docsite/convert_manpages.py docsite/docs/commands/ramalama/*.mdx docsite/docs/platform-guides/*.mdx docs/ramalama-cann.7.md docsite/docs/getting-started/installation.mdx docsite/docusaurus.config.ts
Added clean-generated target in Makefile to remove auto-generated MDX files	Declared 'clean-generated' in PHONY targets Implemented find+grep+rm script to identify and delete generated files	docsite/Makefile
Updated frontmatter titles and headings for configuration manpages	Renamed title from 'ramalama.conf' to 'Configuration File' Renamed title from 'ramalama-oci' to 'OCI Spec' Adjusted top-level headings to match new titles	docsite/docs/configuration/conf.mdx docsite/docs/configuration/ramalama-oci.mdx

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[gemini-code-assist]

Summary of Changes

Hello @ieaves, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request primarily focuses on improving the user experience and maintainability of the documentation site. It addresses various linking inconsistencies, refines the processing of auto-generated documentation content, and enhances the build system for better management of documentation files.

Highlights

• Documentation Linking Improvements: Standardized internal links within the documentation, especially for 'See Also' sections in command manpages, to point to the main command category index (/docs/commands/ramalama/) rather than specific ramalama files. This affects numerous command pages like bench, chat, convert, run, serve, and others, as well as platform guides.
• Auto-generated Content Refinements: Enhanced the convert_manpages.py script to provide more descriptive titles for specific configuration files (ramalama.conf.5.md and ramalama-oci.5.md) and to correctly handle the HISTORY section by moving its content to a page footer and removing its entry from the Table of Contents.
• Docsite Build Process Enhancement: Added a new clean-generated target to the Makefile to facilitate the removal of auto-generated MDX files, improving the documentation build and cleanup workflow.
• Navigation Correction: Updated the 'Getting Started' link in the Docusaurus navbar to directly point to the installation page, providing a more direct entry point for new users.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments or fill out our survey to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[sourcery-ai]

Hey @ieaves - I've reviewed your changes - here's some feedback:

• Consider moving the special-case .5.md title mappings into a centralized dictionary or config to simplify future additions instead of hard-coding if/else branches.
• The hard-coded '/docs/commands/ramalama/' path in convert_link is duplicated in multiple places — extracting it as a constant or config value would reduce duplication and risk of typos.
• Verify that changing the nav entry from '/docs/getting-started' to '/docs/getting-started/installation' won’t confuse users expecting a standalone Getting Started overview page.

Prompt for AI Agents

Please address the comments from this code review:
## Overall Comments
- Consider moving the special-case .5.md title mappings into a centralized dictionary or config to simplify future additions instead of hard-coding if/else branches.
- The hard-coded '/docs/commands/ramalama/' path in convert_link is duplicated in multiple places — extracting it as a constant or config value would reduce duplication and risk of typos.
- Verify that changing the nav entry from '/docs/getting-started' to '/docs/getting-started/installation' won’t confuse users expecting a standalone Getting Started overview page.

## Individual Comments

### Comment 1
<location> `docsite/convert_manpages.py:145` </location>
<code_context>
     if history_match:
         history_text = history_match.group(1).strip()
         content = re.sub(history_pattern, '', content, flags=re.DOTALL)
+        # Remove TOC links to HISTORY since it becomes a footer
+        content = re.sub(r'\s*- \[HISTORY\]\(#history\)\n?', '', content)
         # Add history as footer
         content += f"\n\n---\n\n*{history_text}*"
</code_context>

<issue_to_address>
The regex for removing HISTORY TOC links may miss variants.

The regex should account for variations in spacing, casing, and list markers to ensure all HISTORY TOC links are removed.
</issue_to_address>

<suggested_fix>
<<<<<<< SEARCH
        # Remove TOC links to HISTORY since it becomes a footer
        content = re.sub(r'\s*- \[HISTORY\]\(#history\)\n?', '', content)
=======
        # Remove TOC links to HISTORY since it becomes a footer
        content = re.sub(
            r'^[ \t]*[-*][ \t]*\[[ \t]*history[ \t]*\][ \t]*\([ \t]*#history[ \t]*\)[ \t]*(?:\r?\n)?',
            '',
            content,
            flags=re.IGNORECASE | re.MULTILINE
        )
>>>>>>> REPLACE

</suggested_fix>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[gemini-code-assist]

Code Review

This pull request addresses documentation linking issues and improves the generation process. The changes are clear and directly support the goal of a more robust and user-friendly documentation site.

[rhatdan]

LGTM