Skip to content

Adding New "End User" Documentation to RHDH Local to help with onboarding etc. - #127

Merged
rm3l merged 12 commits into
redhat-developer:mainfrom
benwilcock:main
Nov 21, 2025
Merged

rm3l merged 12 commits into
redhat-developer:mainfrom
benwilcock:main

Conversation

@benwilcock

Copy link
Copy Markdown
Contributor

Description

This PR adds a new getting started guide intended to help brand new Developer Hub users get started quickly. The guide covers essential first-day tasks:

Core Platform Features

  1. 📦 Software Catalog

    • Discovering and browsing components, services, APIs, and resources
    • Filtering by kind, type, owner, lifecycle, and tags
    • Viewing component details, relationships, and dependencies
    • Adding components via templates, manual registration, or bulk import
    • Catalog entities: Components, APIs, Systems, Domains, Users, Groups, Resources
  2. 📋 Software Templates

    • Finding and using templates to create new projects
    • Creating custom templates (authoring guide)
    • Template parameters, actions, and filters
    • Template best practices and tips
  3. 📚 TechDocs

    • Finding and viewing technical documentation
    • Writing TechDocs and adding them to components
    • Making documentation more appealing (formatting, callouts, emojis)
    • TechDocs add-ons and navigation
  4. 🧩 API Browser

    • Discovering and viewing APIs
    • Testing APIs interactively in the browser
    • Linking APIs to components
    • Supported formats (OpenAPI, AsyncAPI, GraphQL)
  5. 🔍 Global Search

    • Quick search from the header
    • Advanced search results page with filtering
    • Searching across components, APIs, documentation, templates, and users
    • Search tips and best practices
  6. 🧭 Navigation

    • Global Header features (Self-Service button, Search, Notifications, Support, Quick Links)
    • Left Hand Navigation sidebar
    • Plugin-added navigation items
  7. 🔌 Extensions (Plugins)

    • Understanding plugins and their role
    • Plugins in navigation and catalog entities
    • Discovering available plugins
    • Dynamic vs. static plugins
    • Requesting plugins from administrators
  8. ⚡ Developer Lightspeed

    • AI-powered assistant for development questions
    • Accessing and using Lightspeed
    • Chat functionality and history
    • Best practices and security considerations

User Experience Features

  1. 🌅 Your First Day

    • Logging in and authentication methods
    • Exploring the homepage and dashboard
    • Using quickstarts to explore features
    • Managing starred items for quick access
    • Profile and settings customization
  2. 🏠 Homepage & Dashboard

    • Welcome greeting and personalized content
    • Getting started action cards
    • Software catalog overview
    • Featured components and templates
    • Quickstarts dock
  3. ⭐ Starred Items

    • Starring components, APIs, and documentation
    • Accessing starred items from the Global Header
    • Organizing frequently used resources
  4. 👤 Profile & Settings

    • Appearance customization (theme, language, sidebar)
    • User profile page with ownership relationships
    • Backstage identity information
    • RHDH version information

Platform Information

  1. 🎯 Platform Overview

    • What Red Hat Developer Hub is and why it's useful
    • Key features and benefits
    • Comparison with CNCF Backstage
    • Enterprise features and capabilities
  2. 💡 Best Practices & Tips

    • Making TechDocs more appealing
    • Top 10 tips for better software templates
    • Catalog best practices
    • Search best practices
  3. 📖 References & Resources

    • Official Red Hat Developer Hub documentation links
    • Backstage community resources
    • Plugin and template libraries
    • Tools and utilities

The content is written for complete beginners, uses engaging language with emojis and callouts consistent with other getting started guides, and includes practical tips and "Next Steps" sections linking to related documentation.

This addresses a gap identified in the documentation review where new users lacked guidance on basic first-day tasks like logging in, understanding the homepage, and personalizing their experience.

Which issue(s) does this PR fix or relate to

  • Fixes #issue_number

PR acceptance criteria

  • Tests updated and passing
  • Documentation updated
  • Built-in TechDocs updated if needed. Note that TechDocs changes may need to be reviewed by a Product Manager and/or Architect to ensure content accuracy, clarity, and alignment with user needs.

How to test changes / Special notes to the reviewer

Testing the Documentation

  1. Preview the new page:

    • Build and serve the TechDocs locally (or view in MkDocs preview)
    • Navigate to "RHDH Guide" in the left hand navigation and open the getting started guide section
    • Verify the page renders correctly with proper formatting, callouts, and links
  2. Verify content accuracy:

    • Check that the content matches the actual Developer Hub functionality
  3. Check consistency:

    • Verify the tone and style match other getting started guides
    • Confirm emoji usage and callout types are consistent
    • Check that "Next Steps" section follows the same pattern as other guides (where used)
  4. Test navigation:

    • Verify all internal links (e.g., navigation.md, software-catalog.md, etc.) are correct
    • Check that application routes (e.g., /catalog, /create) are properly formatted
    • Ensure external links (e.g., official documentation) are valid

Special Notes

  • This is a new section - but some existing content was moved/modified
  • Content is based on actual Developer Hub UI screenshots provided during development
  • The guide is intentionally beginner-friendly and focuses on first-day essentials rather than comprehensive feature coverage

@benwilcock

Copy link
Copy Markdown
Contributor Author
Screenshot 2025-11-20 at 16 05 01

@rhdh-qodo-merge

Copy link
Copy Markdown
Contributor

You are nearing your monthly Qodo Merge usage quota. For more information, please visit here.

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🔒 No security concerns identified
⚡ Recommended focus areas for review

Unwanted Binary File

Binary macOS .DS_Store files are added to the repo. These should be removed from version control and added to .gitignore to avoid bloat and nondeterministic diffs.

����Bud1�� ������� ����
�������������������������������������������������������0��������Ilocblob�����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������
������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������� �������@�������������������������������������������������� �������@������������������������������������������������������ �������@������������������������������������������������������ �������@������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������0�����.�g�i�tIlocblob�������c���_�������������.�g�i�tlg1Scomp�������������.�g�i�tmoDDblob����F����c�A�����.�g�i�tmodDblob����F����c�A�����.�g�i�tph1Scomp������@������.�g�i�t�h�u�bIlocblob�����������_�������������.�g�i�t�h�u�blg1Scomp������"%�����.�g�i�t�h�u�bmoDDblob������ő�c�A�����.�g�i�t�h�u�bmodDblob������ő�c�A�����.�g�i�t�h�u�bph1Scomp������P����
�.�g�i�t�i�g�n�o�r�eIlocblob�����������_�������������.�p�r�_�a�g�e�n�t�.�t�o�m�lIlocblob�������y���_�������������c�a�t�a�l�o�g�-�i�n�f�o�.�y�a�m�lIlocblob�������c���G�����������!�c�o�m�p�o�s�e�-�d�y�n�a�m�i�c�-�p�l�u�g�i�n�s�-�r�o�o�t�.�y�a�m�lIlocblob�����������G�����������!�c�o�m�p�o�s�e�-�w�i�t�h�-�c�o�r�p�o�r�a�t�e�-�p�r�o�x�y�.�y�a�m�lIlocblob�����������G�����������
�c�o�m�p�o�s�e�.�y�a�m�lIlocblob�������y���G�������������c�o�n�f�i�g�sIlocblob�������c���/�������������c�o�n�f�i�g�slg1Scomp������Z������c�o�n�f�i�g�smoDDblob������ő�c�A�����c�o�n�f�i�g�smodDblob������ő�c�A�����c�o�n�f�i�g�sph1Scomp�����������
�d�e�f�a�u�l�t�.�e�n�vIlocblob�����������/�������������d�e�v�e�l�o�p�e�r�-�l�i�g�h�t�s�p�e�e�dIlocblob�����������/�������������d�e�v�e�l�o�p�e�r�-�l�i�g�h�t�s�p�e�e�dlg1Scomp�������6�����d�e�v�e�l�o�p�e�r�-�l�i�g�h�t�s�p�e�e�dmoDDblob������
��e�A�����d�e�v�e�l�o�p�e�r�-�l�i�g�h�t�s�p�e�e�dmodDblob������
��e�A�����d�e�v�e�l�o�p�e�r�-�l�i�g�h�t�s�p�e�e�dph1Scomp������`������d�o�c�sIlocblob�������y���/�������������d�o�c�slg1Scomp�����	�������d�o�c�smoDDblob������
��e�A�����d�o�c�smodDblob������
��e�A�����d�o�c�sph1Scomp�����
�������L�I�C�E�N�S�EIlocblob�������c���������������
�l�o�c�a�l�-�p�l�u�g�i�n�sIlocblob�����������������������
�l�o�c�a�l�-�p�l�u�g�i�n�slg1Scomp�������
���
�l�o�c�a�l�-�p�l�u�g�i�n�smoDDblob������Ƒ�c�A���
�l�o�c�a�l�-�p�l�u�g�i�n�smodDblob������Ƒ�c�A���
�l�o�c�a�l�-�p�l�u�g�i�n�sph1Scomp�����������
�m�k�d�o�c�s�.�y�a�m�lIlocblob�����������������������
�o�r�c�h�e�s�t�r�a�t�o�rIlocblob�������y���������������
�o�r�c�h�e�s�t�r�a�t�o�rlg1Scomp������\����
�o�r�c�h�e�s�t�r�a�t�o�rmoDDblob����B�Ǒ�c�A���
�o�r�c�h�e�s�t�r�a�t�o�rmodDblob����B�Ǒ�c�A���
�o�r�c�h�e�s�t�r�a�t�o�rph1Scomp�������������O�W�N�E�R�SIlocblob�������c���������������&�p�r�e�p�a�r�e�-�a�n�d�-�i�n�s�t�a�l�l�-�d�y�n�a�m�i�c�-�p�l�u�g�i�n�s�.�s�hIlocblob�����������������������	�R�E�A�D�M�E�.�m�dIlocblob�����������������������
�w�a�i�t�-�f�o�r�-�p�l�u�g�i�n�s�-�a�n�d�-�s�t�a�r�t�.�s�hIlocblob�������y�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������� 
���E���
���������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������DSDB������������������������������� ���`����������������������������������������������(�������0�����������@������������������������������������������������������ �������@������������������������������������������������������ �������@�������lob������
��e�A�����d�e�v�e�l�o�p�e�r�-�l�i�g�h�t�s�p�e�e�dph1Scomp������`������d�o�c�sIlocblob�������y���/�������������d�o�c�slg1Scomp�����	�������d�o�c�smoDDblob������
��e�A�����d�o�c�smodDblob������
��e�A�����d�o�c�sph1Scomp�����
�������L�I�C�E�N�S�EIlocblob�������c���������������
�l�o�c�a�l�-�p�l�u�g�i�n�sIlocblob�����������������������
�l�o�c�a�l�-�p�l�u�g�i�n�slg1Scomp�������
���
�l�o�c�a�l�-�p�l�u�g�i�n�smoDDblob������Ƒ�c�A���
�l�o�c�a�l�-�p�l�u�g�i�n�smodDblob������Ƒ�c�A���
�l�o�c�a�l�-�p�l�u�g�i�n�sph1Scomp�����������
�m�k�d�o�c�s�.�y�a�m�lIlocblob�����������������������
�o�r�c�h�e�s�t�r�a�t�o�rIlocblob�������y���������������
�o�r�c�h�e�s�t�r�a�t�o�rlg1Scomp������\����
�o�r�c�h�e�s�t�r�a�t�o�rmoDDblob����B�Ǒ�c�A���
�o�r�c�h�e�s�t�r�a�t�o�rmodDblob��
Broken/Outdated Links Risk

The new navigation references multiple internal docs paths and external docs; validate all links resolve in the built site (e.g., getting-started-rhdh paths, rhdh-local-guide paths) and that external versioned docs URLs are correct.

[Start Learning Developer Hub →](getting-started-rhdh/index.md){ .md-button .md-button--primary }

---

## 🔧 Part 2: RHDH Local User Guide

!!! success "Perfect For: Platform Engineers, DevOps Engineers, and Administrators 🛠️"
    This technical guide is designed for engineers who need to set up, configure, and maintain **RHDH**—using a containerized local environment for testing Red Hat Developer Hub.

### What You'll Learn

This hands-on guide will help you get RHDH Local running and configured. You'll master:

* 🚀 **Setup & Installation** - Get RHDH Local running with Podman or Docker
* ⚙️ **Configuration** - Manage app configuration, dynamic plugins, and catalog entities
* 🔌 **Development Workflows** - Build and test custom plugins locally
* 🎛️ **Operations** - Start, stop, troubleshoot, and maintain your local instance
* 🧪 **Advanced Topics** - GitHub authentication, PostgreSQL setup, corporate proxy simulation, and more

!!! info "What is RHDH Local?"
    RHDH Local is a containerized, local environment that provides a complete Red Hat Developer Hub instance running on your machine. It's designed for **testing, development, education, and template development**—not for production use.

!!! warning "Production Warning"
    RHDH Local is **NOT** a substitute for Red Hat Developer Hub in production. It's designed to help individual developers test various RHDH features locally.

[Start Learning RHDH Local →](rhdh-local-guide/getting-started.md){ .md-button .md-button--primary }
📚 Focus areas based on broader codebase context

UX Consistency

The help menu item title and icon were changed to RHDH Guide with techdocs. Cross-check whether this entry is intended to link to broad RHDH product docs or local instance docs. If the intent is general product documentation, consider aligning the label and icon with existing wording and external docs links, and ensure a direct external link is available elsewhere in the UI. (Ref 1, Ref 5)

title: RHDH Guide
icon: techdocs
priority: 5
to: /catalog/default/system/rhdh-local/docs

Reference reasoning: The referenced documentation emphasizes linking to official Red Hat Developer Hub docs and providing opinionated defaults that guide users to the right resources. Aligning the menu label and icon with the established documentation entry points and conventions helps maintain consistency with how upstream/backstage and RHDH chart docs present official docs links.

📄 References
  1. redhat-developer/rhdh-chart/charts/orchestrator-software-templates/README.md [153-158]
  2. redhat-developer/rhdh-chart/charts/backstage/README.md [13-19]
  3. redhat-developer/rhdh-chart/charts/backstage/README.md [331-352]
  4. redhat-developer/rhdh-chart/charts/orchestrator-software-templates/README.md [23-31]
  5. redhat-developer/rhdh-chart/charts/backstage/README.md [225-247]
  6. redhat-developer/rhdh-chart/charts/orchestrator-software-templates/README.md [32-73]
  7. redhat-developer/rhdh-chart/charts/orchestrator-software-templates/README.md [105-117]
  8. redhat-developer/rhdh-chart/charts/orchestrator-software-templates/README.md [74-85]

@rhdh-qodo-merge rhdh-qodo-merge Bot added the documentation Improvements or additions to documentation label Nov 20, 2025
@rhdh-qodo-merge

Copy link
Copy Markdown
Contributor

You are nearing your monthly Qodo Merge usage quota. For more information, please visit here.

PR Type

Documentation


Description

  • Adds comprehensive "Getting Started with Red Hat Developer Hub" documentation guide for new users covering 15 major topics including Software Catalog, Templates, TechDocs, APIs, Search, Navigation, Extensions, and Developer Lightspeed

  • Creates new getting-started-rhdh/ documentation section with 14 new guides designed for developers and end users with practical step-by-step instructions and best practices

  • Reorganizes main documentation structure (docs/index.md) to split content into two focused paths: one for RHDH users and one for RHDH Local platform engineers

  • Adds new rhdh-local-guide/index.md introduction page explaining RHDH Local use cases and requirements

  • Updates mkdocs.yaml navigation hierarchy to reflect new dual-guide structure with separate "Getting Started" and "RHDH Local User Guide" sections

  • Fixes documentation links throughout existing guides to use relative paths without guides/ prefix and updates image path references for new directory structure

  • Updates help menu configuration in app-config.yaml with improved title and icon

  • Removes redundant top-level headings from existing documentation files and consolidates cross-references

  • Includes new guide comparing RHDH to CNCF Backstage with detailed feature comparison tables

  • Adds comprehensive Software Templates authoring guide for platform engineers with working examples and best practices


File Walkthrough

Relevant files
Miscellaneous
6 files
.DS_Store
macOS system file metadata update                                               

.DS_Store

  • Binary macOS metadata file updated with directory structure
    information
  • Contains serialized file system metadata for the repository root
[link]   
.DS_Store
macOS system file metadata for docs directory                       

docs/.DS_Store

  • Binary macOS metadata file updated for docs directory
  • Reflects new subdirectories including getting-started-rhdh and images
[link]   
.DS_Store
macOS system file metadata for configs directory                 

configs/.DS_Store

  • Binary macOS metadata file updated for configs directory
  • Reflects subdirectories including app-config, catalog-entities,
    dynamic-plugins, and extra-files
[link]   
.DS_Store
macOS system file metadata for developer-lightspeed directory

developer-lightspeed/.DS_Store

  • Binary macOS metadata file updated for developer-lightspeed directory
  • Contains metadata for subdirectories: configs, images, and scripts
[link]   
.DS_Store
macOS system file metadata for orchestrator directory       

orchestrator/.DS_Store

  • Binary macOS metadata file updated for orchestrator directory
  • Reflects subdirectories including configs and workflow-examples
[link]   
.DS_Store
macOS system file metadata for images directory                   

docs/images/.DS_Store

  • Binary macOS metadata file updated for images directory
  • Contains references to image files: Backstage-Full-BlackBG.png,
    editor.png, globalheader.png, RHDH-Homepage.png, software-catalog.png,
    template.png
[link]   
Documentation
25 files
templates-authoring.md
New Software Templates authoring guide for platform engineers

docs/getting-started-rhdh/templates-authoring.md

  • New comprehensive guide for platform engineers on creating Software
    Templates
  • Covers template structure, parameters, steps, and common actions with
    examples
  • Includes best practices, validation patterns, and links to official
    documentation
  • Provides complete working example of a Node.js microservice template
+470/-0 
getting-started.md
Fix documentation links and remove redundant title             

docs/rhdh-local-guide/getting-started.md

  • Removed page title "Getting Started with RHDH Local" (now handled by
    navigation)
  • Updated internal documentation links to use relative paths without
    guides/ prefix
  • Changed 6 cross-references from guides/filename.md to filename.md
    format
+7/-9     
your-first-day.md
New first-day onboarding guide for RHDH users                       

docs/getting-started-rhdh/your-first-day.md

  • New comprehensive guide for first-time RHDH users covering logging in,
    exploring the homepage, using quickstarts, managing starred items, and
    customizing profile settings
  • Includes practical step-by-step instructions with tips and callouts to
    help users get productive quickly
  • Provides context about authentication methods, homepage features, and
    personalization options
+327/-0 
software-catalog.md
Complete Software Catalog user guide and reference             

docs/getting-started-rhdh/software-catalog.md

  • New guide explaining the Software Catalog as the heart of RHDH with
    comprehensive coverage of catalog features and benefits
  • Covers filtering, searching, viewing component details, and best
    practices for using the catalog
  • Includes detailed instructions for adding new items via templates,
    manual registration with catalog-info.yaml, and bulk import methods
+380/-0 
developer-lightspeed.md
Developer Lightspeed AI assistant user guide                         

docs/getting-started-rhdh/developer-lightspeed.md

  • New guide introducing Developer Lightspeed as an AI-powered virtual
    assistant for developers
  • Covers accessing Lightspeed, starting chats, understanding responses
    with citations, and best practices for usage
  • Includes security warnings about data privacy and information about
    developer preview status
+222/-0 
techdocs.md
TechDocs documentation system user guide                                 

docs/getting-started-rhdh/techdocs.md

  • New guide explaining TechDocs as RHDH's documentation system with
    "documentation as code" philosophy
  • Covers finding and viewing TechDocs, writing documentation with
    Markdown and MkDocs, and connecting TechDocs to components
  • Includes best practices for maintaining documentation and references
    to advanced formatting techniques
+170/-0 
index.md
Reorganized documentation structure with dual-audience approach

docs/index.md

  • Restructured main documentation index to split content into two
    focused guides for different audiences
  • Part 1 focuses on using RHDH for developers and new users; Part 2
    focuses on RHDH Local for platform engineers
  • Added decision guide to help users choose the appropriate
    documentation path based on their role and needs
+69/-44 
search.md
Universal search feature user guide                                           

docs/getting-started-rhdh/search.md

  • New comprehensive guide covering RHDH's universal search capabilities
    from both the Global Header and dedicated search results page
  • Covers quick search features, search result types, advanced filtering,
    and search best practices
  • Includes troubleshooting tips and search shortcuts for finding
    components, APIs, documentation, and templates
+211/-0 
comparison.md
RHDH vs CNCF Backstage comparison guide                                   

docs/getting-started-rhdh/comparison.md

  • New guide comparing Red Hat Developer Hub to CNCF Backstage with
    detailed feature comparison tables
  • Covers core features, enterprise & operations, security & governance,
    plugins & extensibility, and advanced features
  • Provides decision guidance for choosing between RHDH and Backstage
    based on organizational needs
+138/-0 
navigation.md
Navigation and interface orientation guide                             

docs/getting-started-rhdh/navigation.md

  • New guide explaining RHDH's navigation structure including Global
    Header and Left Hand Navigation sidebar
  • Covers Self-Service button, Support button, Notifications, Search,
    Quick Links, User Profile menu, and standard navigation items
  • Includes navigation best practices and tips for organizing and
    customizing the user experience
+177/-0 
apis.md
API browser discovery and testing guide                                   

docs/getting-started-rhdh/apis.md

  • New guide introducing the API browser for discovering, viewing, and
    testing APIs in RHDH
  • Covers finding APIs through navigation and catalog, viewing API
    details, and interactive API testing capabilities
  • Explains API registration and linking to components with information
    about supported API formats
+148/-0 
index.md
RHDH Local guide introduction and overview                             

docs/rhdh-local-guide/index.md

  • New index page for RHDH Local User Guide section explaining what RHDH
    Local is and its primary use cases
  • Covers testing & configuration, education & learning, and local plugin
    development scenarios
  • Includes key requirements and links to detailed guides for setup and
    operations
+103/-0 
templates.md
Software Templates user guide and reference                           

docs/getting-started-rhdh/templates.md

  • New guide explaining Software Templates as self-service workflows for
    creating projects and components
  • Covers finding and using templates, filtering and searching templates,
    and common use cases
  • Includes information about template forms, parameters, and references
    to template authoring and examples
+145/-0 
references.md
References and external documentation links                           

docs/getting-started-rhdh/references.md

  • Updated references page with links to official RHDH documentation,
    Backstage resources, and community tools
  • Reorganized to focus on getting started guide scope rather than RHDH
    Local specific workflows
  • Added links to RHDH plugins, software templates library, and
    development tools
+11/-26 
extensions.md
Extensions and plugins overview guide                                       

docs/getting-started-rhdh/extensions.md

  • New guide explaining Extensions (Plugins) as the mechanism for
    extending RHDH capabilities
  • Covers plugins in navigation, plugins in catalog entities, discovering
    plugins, and dynamic vs static plugins
  • Includes guidance on requesting plugins from administrators and
    references to plugin management documentation
+86/-0   
mkdocs.yaml
Documentation navigation structure reorganization               

mkdocs.yaml

  • Restructured navigation hierarchy to separate "Getting Started With
    Red Hat Developer Hub" from "RHDH Local User Guide"
  • Added new documentation pages for getting started guide including
    highlights, comparison, first-day, navigation, search, catalog, APIs,
    TechDocs, templates, extensions, and Lightspeed
  • Reorganized existing guides under rhdh-local-guide/ directory
    structure
+31/-22 
highlights.md
RHDH key features and benefits overview                                   

docs/getting-started-rhdh/highlights.md

  • New guide highlighting key features and benefits of Red Hat Developer
    Hub
  • Covers turn-key solution, unified interface, software templates,
    self-service capabilities, extensibility, enterprise support, and
    deployment options
  • Provides context for why RHDH is valuable and links to related feature
    guides
+62/-0   
index.md
Getting started guide introduction and fundamentals           

docs/getting-started-rhdh/index.md

  • New comprehensive introduction to Red Hat Developer Hub explaining
    what it is and why it's valuable
  • Covers the developer experience problem, how RHDH solves it, key
    benefits for developers/platform teams/organizations
  • Includes what makes RHDH special and navigation to related getting
    started guides
+92/-0   
dynamic-plugins-management.md
Add Dynamic Plugins Factory conversion guide                         

docs/rhdh-local-guide/dynamic-plugins-management.md

  • Removed the top-level heading # Dynamic Plugin Management
  • Added comprehensive new section "Converting Static Plugins to Dynamic
    Plugins" covering the RHDH Dynamic Plugins Factory tool
  • Included details on batch conversion, customization support, and
    container-based workflow
  • Provided a minimal example command for converting the TODO plugin
    using Podman
+54/-2   
help-and-contrib.md
Reorganize documentation structure and update references 

docs/rhdh-local-guide/help-and-contrib.md

  • Removed the top-level heading # Getting Help & Contributing
  • Restructured and expanded the documentation structure tree to reflect
    new organization with getting-started-rhdh/ and rhdh-local-guide/
    directories
  • Added mkdocs.yaml and OWNERS file references
  • Updated cross-reference link to point to the new location of "Making
    Your TechDocs More Appealing"
+33/-13 
github-auth.md
Remove heading and fix relative link paths                             

docs/rhdh-local-guide/github-auth.md

  • Removed the top-level heading # GitHub Authentication Setup
  • Updated relative link references to use simplified paths within the
    same directory (getting-started.md and help-and-contrib.md)
+2/-4     
making-techdocs-appealing.md
Fix typos and update image path references                             

docs/getting-started-rhdh/making-techdocs-appealing.md

  • Fixed typo: "th top" changed to "the top"
  • Updated image path from ./images/backstage-logo-cncf.svg to
    ../images/backstage-logo-cncf.svg to reflect new directory structure
  • Fixed acronym expansion: "Compting" corrected to "Computing" in the
    CNCF abbreviation definition
+3/-3     
plugins-guide.md
Remove heading and fix configuration link reference           

docs/rhdh-local-guide/plugins-guide.md

  • Removed the top-level heading # Local Plugin Development
  • Updated cross-reference link from
    /rhdh-local/additional-config-guides/changing-config.md to
    configuration.md to reflect new documentation structure
+1/-3     
operating-rhdh-local.md
Remove heading and fix help link reference                             

docs/rhdh-local-guide/operating-rhdh-local.md

  • Removed the top-level heading # Operating RHDH Local
  • Updated relative link reference for "Help & Contributing" from
    ../help-and-contrib.md to help-and-contrib.md to reflect same
    directory location
+1/-3     
configuration.md
Remove heading and simplify link reference                             

docs/rhdh-local-guide/configuration.md

  • Removed the top-level heading # Configuration
  • Updated relative link reference for GitHub auth guide from
    ./github-auth.md to github-auth.md for consistency
+1/-3     
Configuration changes
1 files
app-config.yaml
Update help menu configuration and icon                                   

configs/app-config/app-config.yaml

  • Updated help menu item title from "RHDH Local Guide" to "RHDH Guide"
  • Changed help menu icon from help to techdocs for better visual
    consistency
+2/-2     
Additional files
8 files
ten_template_tips.md [link]   
comparison.md +0/-31   
features.md +0/-23   
rhdh.md +0/-18   
container-image-guide.md +0/-2     
corporate-proxy-setup-sim.md +0/-2     
loading-content.md +0/-2     
postgresql-guide.md +0/-2     

@rhdh-qodo-merge

rhdh-qodo-merge Bot commented Nov 20, 2025 •

Copy link
Copy Markdown
Contributor

You are nearing your monthly Qodo Merge usage quota. For more information, please visit here.

PR Code Suggestions ✨

Explore these optional code suggestions:

CategorySuggestion                                                                                                                                    Impact
Possible issue
Fix a broken internal link

Update the broken link for "Comparing Red Hat Developer Hub to CNCF Backstage"
to point to the correct new file path.

docs/rhdh-local-guide/index.md [99]

-Want to understand the differences in detail? See our [**Comparing Red Hat Developer Hub to CNCF Backstage**](guides/comparison.md) guide for a comprehensive feature comparison.
+Want to understand the differences in detail? See our [**Comparing Red Hat Developer Hub to CNCF Backstage**](../getting-started-rhdh/comparison.md) guide for a comprehensive feature comparison.
  • Apply / Chat
Suggestion importance[1-10]: 6

__

Why: The suggestion correctly identifies a broken link to the comparison.md file, which was caused by the documentation refactoring in this PR, and provides the correct path to fix it.

Low
General
Fix typo in acronym definition

Fix a typo in the "CNCF" abbreviation definition, changing "Compting" to
"Computing".

docs/getting-started-rhdh/making-techdocs-appealing.md [183]

-*[CNCF]: Cloud Native Compting Foundation
+*[CNCF]: Cloud Native Computing Foundation

[Suggestion processed]

Suggestion importance[1-10]: 3

__

Why: The suggestion correctly identifies and fixes a typo in the documentation, which improves the accuracy of the content.

Low
  • More

@rm3l rm3l left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Thanks for these comprehensive and helpful docs 😍
Minor comment about .DS_STORE files.

Comment thread configs/.DS_Store Outdated
Comment thread docs/getting-started-rhdh/making-techdocs-appealing.md

@rm3l rm3l left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, there are some broken links to fix.
I think the main README.md should be updated as well with the right paths: https://github.com/benwilcock/rhdh-local/blob/main/README.md?plain=1#L60-L65

Comment thread docs/rhdh-local-guide/index.md Outdated
Comment thread docs/rhdh-local-guide/index.md Outdated
Comment thread docs/rhdh-local-guide/index.md Outdated

@rm3l rm3l left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/lgtm

@openshift-ci openshift-ci Bot added the lgtm label Nov 21, 2025
@rm3l
rm3l merged commit fe6623f into redhat-developer:main Nov 21, 2025
25 checks passed
@rhdh-qodo-merge rhdh-qodo-merge Bot mentioned this pull request Aug 3, 2026
4 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation lgtm Review effort 2/5

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants