Overcoming the .dox Highlighting Issue in CLion

When writing documentation for C and C++ projects using Doxygen, developers often use .dox files for out-of-source documentation—such as standalone guides, main pages (@mainpage), or architecture overviews. Unfortunately, CLion (and many other JetBrains IDEs) does not support the .dox file extension out of the box.

If you have tried forcing CLion to treat .dox files as C/C++ files, you likely ran into two frustrating issues:

  • The file is marked as not belonging to any CMake or compilation target, which degrades code analysis.
  • Doxygen tags like @param, @brief, or \section are rendered as plain comments without rich syntax coloring.

Fortunately, there are three practical ways to fix this and get clean, readable syntax highlighting for your Doxygen files in CLion.

Method 1: Map .dox to C++ and Add It to CMake (Recommended)

CLion's rich Doxygen highlighting is powered by its C/C++ language engine (clangd). To activate full Doxygen keyword highlighting, the IDE needs two things: it must recognize the file format, and the file must be tracked by your project model (such as CMake).

Step 1: Associate the Extension with C/C++

  1. Open CLion and navigate to Settings (or Preferences on macOS) > Editor > File Types.
  2. Scroll down the Recognized File Types list and select C/C++.
  3. In the File name patterns section at the bottom, click the + icon and enter *.dox.
  4. Click Apply.

Step 2: Add .dox Files to Your CMakeLists.txt

By default, CLion provides limited highlighting to files that are not registered in the project's build system. To resolve this without compiling the documentation, register the .dox files using a dummy custom target:

# CMakeLists.txt
file(GLOB_RECURSE DOX_FILES "docs/*.dox")
add_custom_target(doxygen_docs SOURCES ${DOX_FILES})

Once CMake reloads, CLion will treat your .dox file as an active part of the project. If your documentation is wrapped in standard C/C++ comment delimiters (such as /** ... */ or /*! ... */), CLion will fully colorize all Doxygen commands and tags.

Method 2: Use a TextMate Bundle for Native Doxygen Highlighting

If you prefer not to modify your CMakeLists.txt or wrap everything in C-style comment markers, you can import a Doxygen syntax definition via JetBrains' built-in TextMate Bundles support.

  1. Download or clone a standard Doxygen TextMate bundle (for example, search GitHub for textmate doxygen bundle or export one from VS Code).
  2. In CLion, go to Settings > Editor > TextMate Bundles.
  3. Click the + button and select the folder containing the Doxygen bundle.
  4. Head to Editor > File Types, locate TextMate, and ensure *.dox is registered as an extension.

This method provides custom syntax coloring for tags without requiring a project target or C++ block comments.

Method 3: Migrate to Markdown (.md) Files

If you are starting a new documentation section or are open to refactoring, consider using Markdown instead of .dox. Modern versions of Doxygen provide first-class support for standard .md files.

You can embed Doxygen commands directly into Markdown:

# Architecture Overview {#arch_overview}

This page describes the core architecture.

@see CoreEngine

Switching to .md offers immediate advantages:

  • CLion provides native Markdown rendering, syntax coloring, and live preview.
  • Documentation looks clean and readable both on platforms like GitHub/GitLab and inside the rendered Doxygen HTML output.
  • No additional CMake targets or file association tweaks are required.

Conclusion

For most developers, Method 1 (mapping *.dox to C/C++ and exposing it via an add_custom_target in CMake) provides the smoothest workflow, enabling CLion's built-in Doxygen parser. Alternatively, migrating standalone docs to Markdown is a future-proof approach that offers seamless editing and previewing right inside the IDE.