Introducing the Microsoft Learn-Inspired HTML Preview

We are excited to announce the preview release of a new HTML output style for DocInsight that emulates the modern look and feel of Microsoft Learn documentation. This new style is designed to provide a modern, user-friendly experience for readers, significantly improving the navigation and consumption of technical content.

You can check out the live online demo here: Spring4D API Documentation.

Features

This release isn’t just a visual skin; it includes functional improvements designed to help users find information faster.

  • Fully Responsive: The layout automatically adapts to any screen size, ensuring your documentation looks professional on desktops, tablets, and mobile devices.
  • Theme-Aware: Built-in support for Light and Dark modes that respects the user’s system preferences automatically.
  • Enhanced Navigation: Improved discoverability with a robust Table of Contents, breadcrumb trails, and a dynamic “On this Page” right-rail navigation.
  • Overloads: Method and function overloads are grouped cleanly to reduce page clutter while keeping technical details accessible.
  • Instant Search: A fast, client-side search experience that delivers results instantly as you type.

Performance

The performance of HTML rendering has been significantly improved in this release. We conducted benchmark tests using the Spring4D developer branch (7,762 topics) and the WinRTL project (225,360 topics). The results below demonstrate the generation speed improvements:

Dry-run

With --dry-run option, we can observe performance of parsing and HTML rendering without generating any files.

Spring4D: 8X (546 ms vs 4.76s)

WinRTL: 18X (5s vs 90s)

Real Building

While I/O remains the primary bottleneck in the documentation generation process, the performance results still demonstrate noticeable improvements:

Spring4D: 2X (2.2s vs 5.7s)

WinRTL: 2X (62s vs 137s)

AntiVirus Real-time protection

We have observed that some AntiVirus software may significant slow down the HTML generation process due to real-time file scanning. Windows Defender, for instance. If you use a generic folder name like output as your documentation output directory, it may trigger real-time protection frequently. We recommend trying use other names such as docs\dist.

Get Started

To generate documentation in the new Microsoft Learn-style HTML format, simply download the latest version and use the following command with the new theme flag:

docinsight build -f html --theme learn

Tip: In the Delphi IDE, you can use DocInsight > Tools > DocInsight Command Prompt to run docinsight.exe without modifying your system PATH.

Limitations

As this is a preview release, there are a few current limitations to be aware of:

  • HTML Only: The new style is currently exclusive to HTML output. It is not yet applicable to CHM output or Delphi IDE extensions.
  • Search Index Size: The instant search index is generated for client-side search. For massive projects (e.g., WinRTL with 200k+ topics), the index size can be substantial (approx. 20MB), which may impact initial load times.
  • Segoe UI Font: Because Segoe UI is a copyrighted font, we are unable to distribute its font files. Most Windows users will already have it installed, though the appearance may vary slightly on non-Windows browsers.

Notable bug fixes in this release

  • Improved error messaging for mismatched tags.
  • Resolved a “file path too long” issue caused by complex method signatures in the new MS Learn output.
  • Fixed a Delphi IDE freeze that occurred when writing documentation with DocInspector with CnWizards installed.
  • Fixed a DocInsight panic that occurred when a search path entry was not a valid directory.
  • Fixed an issue where DocInspector displayed empty results for unresolved source files.

Upcoming plans

We are actively working on the next steps for DocInsight:

  • Designing a new manifest system with versioning, filtering, and more customization options.
  • Introducing Markdown-based help authoring with cross-referencing support.
  • Updating IDE extensions to support theme-awareness and the new MS Learn style.
  • Bringing the new style to CHM output.

Limited time Offer for Black Friday

Celebrate the new release with our Black Friday deal!

  • The Deal: Save 25% off new registrations.
  • Code: Use Coupon Code BF2025 at checkout.
  • Due to store limitations, please contact us for purchases of more than one license.

We hope you enjoy using the new Microsoft Learn-style HTML output in DocInsight! Your feedback is valuable to us, so please don’t hesitate to share your thoughts and suggestions.