DOCSEARCHbyAlgolia
Submit Docs

Doxygen Awesome CSS

repository·main·Indexed 23 days ago

https://github.com/jothepro/doxygen-awesome-css

A modern, customizable CSS theme for Doxygen HTML documentation featuring dark mode support and a clean design. It includes multiple layout options, such as a Base Theme and a Sidebar-Only Theme, and provides JavaScript extensions for dark mode toggling, fragment copy buttons, paragraph linking, interactive TOC, and tabbed list content. Compatible with Doxygen versions 1.9.1 - 1.9.4 and 1.9.6 - 1.16.1.

Tokens
4.6K
Snippets
19
Records
22
Agent score
80%

What's inside doxygen-awesome-css

  1. Install and customize the Fragment Copy Button extension

    main

    Displays a copy button when hovering over code fragments.

    Installation

    1. In your Doxyfile, add:
      • HTML_EXTRA_FILES: doxygen-awesome-fragment-copy-button.js
      • HTML_COPY_CLIPBOARD: NO (Required if using Doxygen >= 1.10.0).
    2. In header.html, include the script at the end of the <head> and initialize:
    <head>
    <!-- ... -->
    <script type="text/javascript" src="$relpath^doxygen-awesome-fragment-copy-button.js"></script>
    <script type="text/javascript">
        DoxygenAwesomeFragmentCopyButton.init()
    </script>
</head>

    Customization

    Note: All customizations must be applied before calling .init().

    • Change tooltip: DoxygenAwesomeFragmentCopyButton.title = "Copy to clipboard"
    • Change icons (SVG only):
      DoxygenAwesomeFragmentCopyButton.copyIcon = `<svg ...>`
DoxygenAwesomeFragmentCopyButton.successIcon = `<svg ...>`
    <script type="text/javascript" src="$relpath^doxygen-awesome-fragment-copy-button.js"></script>
<script type="text/javascript">
    DoxygenAwesomeFragmentCopyButton.init()
</script>

  2. Install Doxygen Awesome CSS via CMake FetchContent

    main

    For CMake-based projects, use the FetchContent module to download the repository during the configuration stage. You can then use FetchContent_GetProperties to retrieve the source directory path, which is useful for referencing the CSS files in your Doxyfile.in via the HTML_EXTRA_STYLESHEET field.

    include(FetchContent)
FetchContent_Declare(
    doxygen-awesome-css
    URL https://github.com/jothepro/doxygen-awesome-css/archive/refs/heads/main.zip
)
FetchContent_MakeAvailable(doxygen-awesome-css)

# Save the location the files were cloned into
# This allows us to get the path to doxygen-awesome.css
FetchContent_GetProperties(doxygen-awesome-css SOURCE_DIR AWESOME_CSS_DIR)

# Generate the Doxyfile
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/doc/Doxyfile.in)
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)

    In your Doxyfile.in, reference the path like this:

    HTML_EXTRA_STYLESHEET  = @AWESOME_CSS_DIR@/doxygen-awesome.css

  3. Prepare a custom HTML header template for Doxygen extensions

    main

    Most JavaScript extensions in doxygen-awesome-css require modifications to your Doxygen HTML header. To use them, you must first generate a default header template from Doxygen and then reference it in your Doxyfile.

    1. Generate the template using the Doxygen command line:
      doxygen -w html header.html delete_me.html delete_me.css
    2. Reference the template in your Doxyfile:
      HTML_HEADER = header.html
    doxygen -w html header.html delete_me.html delete_me.css

  4. Install and customize the Dark Mode Toggle extension

    main

    Adds a button next to the search bar to manually toggle between light and dark themes.

    Installation

    1. In your Doxyfile, add the following:
      • HTML_EXTRA_FILES: doxygen-awesome-darkmode-toggle.js
      • HTML_EXTRA_STYLESHEET: doxygen-awesome-sidebar-only-darkmode-toggle.css (Required only if using the sidebar-only theme variant).
    2. In your header.html, include the script at the end of the <head> and initialize it:
    <head>
    <!-- ... -->
    <script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>
    <script type="text/javascript">
        DoxygenAwesomeDarkModeToggle.init()
    </script>
</head>

    Customization

    Note: All customizations must be applied before calling .init().

    • Change tooltip: DoxygenAwesomeDarkModeToggle.title = "Your Tooltip Text"
    • Change icons (Emoji or SVG):
      DoxygenAwesomeDarkModeToggle.lightModeIcon = '🌞'
DoxygenAwesomeDarkModeToggle.darkModeIcon = `<svg ...>...</svg>`
    <script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>
<script type="text/javascript">
    DoxygenAwesomeDarkModeToggle.init()
</script>

  5. Adjust Doxygen color settings for better blending

    main

    While the theme overrides most colors using --primary-color-* variables, some small images and graphics are not covered. To ensure these blend well with the theme, adjust the Doxygen color settings in your Doxyfile.

    For the default color scheme, use the following values:

    # Doxyfile
HTML_COLORSTYLE_HUE    = 209
HTML_COLORSTYLE_SAT    = 255
HTML_COLORSTYLE_GAMMA  = 113

  6. Install and customize the Paragraph Linking extension

    main

    Adds a button that appears on hover behind headlines, allowing users to create permanent links to that section.

    Installation

    1. In your Doxyfile, add:
      • HTML_EXTRA_FILES: doxygen-awesome-paragraph-link.js
    2. In header.html, include the script at the end of the <head> and initialize:
    <head>
    <!-- ... -->
    <script type="text/javascript" src="$relpath^doxygen-awesome-paragraph-link.js"></script>
    <script type="text/javascript">
        DoxygenAwesomeParagraphLink.init()
    </script>
</head>

    Customization

    Note: All customizations must be applied before calling .init().

    • Change tooltip: DoxygenAwesomeParagraphLink.title = "Link to section"
    • Change icon (Emoji or SVG): DoxygenAwesomeParagraphLink.icon = "¶"
    <script type="text/javascript" src="$relpath^doxygen-awesome-paragraph-link.js"></script>
<script type="text/javascript">
    DoxygenAwesomeParagraphLink.init()
</script>

  7. Install and customize the Interactive TOC extension

    main

    Visualizes reading progress by highlighting the active section in the Table of Contents (TOC) on large screens. On small screens, it provides a toggleable menu.

    Installation

    @note For Doxygen 1.14.0+, you must set PAGE_OUTLINE_PANEL=NO in your Doxyfile.

    1. In your Doxyfile, add:
      • HTML_EXTRA_FILES: doxygen-awesome-interactive-toc.js
    2. In header.html, include the script at the end of the <head> and initialize:
    <head>
    <!-- ... -->
    <script type="text/javascript" src="$relpath^doxygen-awesome-interactive-toc.js"></script>
    <script type="text/javascript">
        DoxygenAwesomeInteractiveToc.init()
    </script>
</head>

    Customization

    • Change active headline offset: DoxygenAwesomeInteractiveToc.topOffset = 45 (Smaller values mean the headline must be closer to the top of the viewport to trigger highlighting).
    • Disable hiding TOC on mobile: DoxygenAwesomeInteractiveToc.hideMobileMenu = false (The menu will be open by default but still manually hideable).
    <script type="text/javascript" src="$relpath^doxygen-awesome-interactive-toc.js"></script>
<script type="text/javascript">
    DoxygenAwesomeInteractiveToc.init()
</script>

  8. Customize the theme using CSS variables

    main

    The theme is parameterized using CSS variables. To customize the appearance, create a custom.css file and override the variables within the html selector.

    Setup

    1. Create a custom.css file.
    2. In your Doxyfile, add both the theme and your custom stylesheet to HTML_EXTRA_STYLESHEET:
      HTML_EXTRA_STYLESHEET = doxygen-awesome.css custom.css
    3. In custom.css, override variables inside the html tag selector for light mode.

    Dark Mode Overrides

    Depending on whether you use the doxygen-awesome-darkmode-toggle.js extension, use one of the following methods for dark mode:

    If dark-mode toggle IS installed:

    html.dark-mode {
    /* define dark-mode variable overrides here */
}

    If dark-mode toggle is NOT installed (uses system preference):

    @media (prefers-color-scheme: dark) {
    html:not(.light-mode) {
        /* define dark-mode variable overrides here */
    }
}
    html {
    /* override light-mode variables here */
}

  9. Install Doxygen Awesome CSS system-wide

    main

    You can install the theme files to your system by running make install. By default, files are installed to /usr/local/share/. You can specify a custom installation path using the PREFIX variable.

    make install
# Or with a custom path:
make PREFIX=/my/custom/path install

  10. Format and style tables

    main

    The theme provides several ways to modify the default left-aligned, content-width table behavior:

    • Centering: Wrap the table in a <center> HTML tag.
    • Full Width: Wrap the table in a div with the full_width_table class. Warning: This disables overflow scrolling and may cause content to be cut off on small screens.
    <!-- Centered Table -->
<center>
    | Col 1 | Col 2 |
    |-------|-------|
    | Val 1 | Val 2 |
</center>

<!-- Full Width Table -->
<div class="full_width_table">
    | Col 1 | Col 2 |
    |-------|-------|
    | Val 1 | Val 2 |
</div>
    <center>
    | This table | is centered          |
    |------------|----------------------|
    | test 1     | test 2               |
</center>

<div class="full_width_table">
    | This table | spans the full width |
    |------------|----------------------|
    | test 1     | test 2               |
</div>

  11. Use the Tabs extension for list content

    main

    Allows arranging list items into clickable tabs.

    Installation

    1. In your Doxyfile, add:
      • HTML_EXTRA_FILES: doxygen-awesome-tabs.js
    2. In header.html, include the script at the end of the <head> and initialize:
    <head>
    <!-- ... -->
    <script type="text/javascript" src="$relpath^doxygen-awesome-tabs.js"></script>
    <script type="text/javascript">
        DoxygenAwesomeTabs.init()
    </script>
</head>

    Usage

    Wrap your list in a div with the class tabbed. Each list item must contain an element with the class tab-title to serve as the tab label.

    <div class="tabbed">

- <b class="tab-title">Tab 1</b> This is the content of tab 1
- <b class="tab-title">Tab 2</b> This is the content of tab 2

</div>
    <script type="text/javascript" src="$relpath^doxygen-awesome-tabs.js"></script>
<script type="text/javascript">
    DoxygenAwesomeTabs.init()
</script>

  12. Force Light or Dark mode

    main

    By default, the theme follows the browser's color preference. To override this behavior and force a specific mode, add the corresponding class to the <html> tag in your header template.

    Note: This method only works if you are not using the dark-mode toggle extension.