Docfx: Create a material style theme

Created on 12 Jul 2017 · 6Comments · Source: dotnet/docfx

the layout of Google API theme looks quite similar to docfx's

Area-Themes help-wanted

Source

vicancy

👍8

Most helpful comment

The Material Theme for MkDocs could be used as the base for the docfx theme
https://squidfunk.github.io/mkdocs-material/

There are already a couple of ports of that theme to other generators:

ovasquez on 29 Jan 2018

👍3

All 6 comments

shyamal890 on 22 Aug 2017

The Material Theme for MkDocs could be used as the base for the docfx theme
https://squidfunk.github.io/mkdocs-material/

There are already a couple of ports of that theme to other generators:

ovasquez on 29 Jan 2018

👍3

Creating a theme here shouldn't be a concern of the core project, rather simplifying the creation of themes should be.

There are serious markup, css styling and accessibility issues with the default templates and I would suggest getting someone with UX/frontend skills involved to help clean it up.

I've noted in an attempt to style the default output:

Removal of outline styles.
Lack of aria attribution for menu items
Over specificity of css selectors
Floating items without clearing containers
Absolute and fixed positioning where it simply isn't required.
Over complication of markup for iconography
Tiny clickable areas (side nav)
No use of sections/articles.
Very limited use of Html5 roles
Old JQuery library inclusion

And that's just scratching the surface.

This work would require a major version as it would introduce breaking changes.

I'm more than a little disappointed that MS didn't strive to make the output more inclusive.

JimBobSquarePants on 20 Mar 2018

👍2

@JimBobSquarePants,

We know there are lots of areas to improve in docfx and creating a customized theme is just one of the outstanding problems. Like you mentioned, a major breaking change is needed to modernize the system. We had some initial discussions around how to build the next version of docfx and customized themes is definitely a big topic. It is still at the very early stage, but we'd like to hear all food for thoughts.