question: is there a any interest in improving the default style sheet for html?

[graph]

Current style sheet is full width of the browser. A nicer thing would be to set a max-width to 800. When copy & pasting enums in html it always copies a space at the end. There is other modern improvements that could be made. Or will the style sheet stay the same to be backwards compatible with customizations people have done already?

[mosra]

Shameless self-promo: have you seen the m.css Doxygen theme? It has various usability improvements as well as mobile-friendly rendering and blazing-fast search.

[septatrix]

I would really like a rework of the current theme.

However I think a complete redesign like some of the third-party themes is problematic. Not only does it differ a lot from the current theme but it also changes the html structure of the output. As some people may query certain docs this would be backwards incompatible. Instead I would propose to update the current theme whilst keeping the html structure (at least the content, maybe small modifications to header and footer template) as these could all be suppressed by a user by just passing the old files during the build process as options.

What I would like to see is:

• move to a flat theme
• solid background
• collapsible sidebar
• responsive theme for mobile devices
• dark mode using @media (prefers-color-scheme: dark)

If the maintainers have nothing to object to this proposal/issue and I have some free time I may try to draft a demo.

[doxygen]

@septatrix yes that sounds good. I don’t consider myself to be a good web designer, so I tend to not give it enough attention. So I’d appreciate any help to improve the look and feel of the output.

[albert-github]

Things to be considered are (in my opinion) also:

• the fact that the HTML documentation is used as base for the CHM output as well
• the layout / colors are very individually, In the past it was considered e.g. in leaflets to have a lot of colors making it unreadable. Also when I personally see a site with a black background it straight a way give me a negative impression and also sites with fancy letter types or big white / transparent borders result in the same negative ideas. On a site the content should be the most important and the possibility to find things.

[jothepro]

I've written a custom theme for myself that introduces a flat design and improves mobile usability a bit: https://github.com/jothepro/doxygen-awesome-css

@graph maybe you want to give it a try? By default it has a maximum content-width of 900px, but you can configure it to any width you like.

@doxygen I've put quite a lot of work into my theme. If you like it I'd be happy to help bring some of my changes into the default theme!

[doxygen]

@jothepro I really like what you made. Very nice work!

I will start looking into what it takes to integrate your work into doxygen. Would be nice if you want to help to further improve it over time.

As a start I made the "sidebar-only" layout more officially supported, so it can also be made resizable, see https://github.com/doxygen/doxygen/commit/a9d29861fe6ad3c182d6cded2e3636a20086fc96

Some further integration ideas:

• make dark/light mode a configuration option. Values: DARK, LIGHT, AUTO, default AUTO.
• make the variable definitions in the CSS a separate file that can be overruled and for which doxygen can generate the default settings.
• merge the current CSS definition with the awesome-CSS definitions.
• figure out what to do with the HTML_COLORSTYLE options (probably just deprecate them).

[jothepro]

Hi @doxygen, I'm very happy to hear that you like it! :)

Would be nice if you want to help to further improve it over time.

I will continue to support & improve my theme! If you decided to migrate portions of it to the official theme, I'd be happy to help to improve them as well!

As a start I made the "sidebar-only" layout more officially supported

That's super cool!

One thought came up to me though: My theme relies on the top-bar navigation on small (mobile) screens. If one disables it with (FULL_SIDEBAR = YES), navigation on mobile relies on the (hidden on small screens by default) sidebar, which is not optimal. Maybe on mobile screens there should be a hamburger menu to open the sidebar menu?

Some further integration ideas: [...] merge the current CSS definition with the awesome-CSS definitions.

I'm happy to hear that you are that confident about my theme! Currently I feel like it needs more time and user feedback to mature to sth that I'd be confident shipping to all doxygen users... 🤔 Maybe instead of merging it with the current CSS it should be a separate option that can be enabled as experimental feature to start with?

[doxygen]

Would be nice if you want to help to further improve it over time.

I will continue to support & improve my theme! If you decided to migrate portions of it to the official theme, I'd be happy to help to improve them as well!

Ok, good to hear!

As a start I made the "sidebar-only" layout more officially supported

That's super cool!

One thought came up to me though: My theme relies on the top-bar navigation on small (mobile) screens. If one disables it with (FULL_SIDEBAR = YES), navigation on mobile relies on the (hidden on small screens by default) sidebar, which is not optimal. Maybe on mobile screens there should be a hamburger menu to open the sidebar menu?

I have to look into that. A hamburger style menu sounds like a good approach indeed.

Some further integration ideas: [...] merge the current CSS definition with the awesome-CSS definitions.

I'm happy to hear that you are that confident about my theme! Currently I feel like it needs more time and user feedback to mature to sth that I'd be confident shipping to all doxygen users... 🤔 Maybe instead of merging it with the current CSS it should be a separate option that can be enabled as experimental feature to start with?

Good idea I think.

Based on Albert's concerns above I already did a small test on Windows to produce CHM output (using Microsoft's ancient HtmlHelp compiler). It doesn't seem to understand the modern CSS concepts (like var(), calc() and friends) since it seems to be hard-coded to use IE with IE7 rendering mode 😦. So if we still want to support it (even though Microsoft already gave up on their own tool long ago) then maybe we should let doxygen resolve these variables (and other functions) internally before writing the then simpler CSS output.

[albert-github]

In my previous comment I had some concern for CHM but this is of course also valid for other output formats that use the HTML output like QHP, docsets, eclipsehelp (as far as I quickly could see). Maybe these formats are even more antiquated (as I don't see, as far as I can remember, questions about these formats popping up).

[doxygen]

I think the best approach could be to have a very basic looking (but supported) version of the HTML output that still looks ok-ish and works with all indexing tools, and then have an option to switch to a more enhanced output that would require a modern web browser (and is probably going to be used by >95% of the users). Ideally this is what the template engine (-T option) was meant to make easy, so maybe I should complete that first.

[tlsa]

It would be great to have a Read the Docs theme, that generated output that was a match for that style. Their documentation style is very nice looking, clean and modern.

[2bndy5]

figure out what to do with the HTML_COLORSTYLE options (probably just deprecate them).

I would appreciate a way to use these variables in the template html files via a corresponding variable (ie $html_colorstyle_*). Or maybe provide them as CSS vars in the generated doxygen.css.

As far as material design goes these vars could be used like mkdocs-material theme's primary color option.