Modernize the default theme

[nojaf]

Intro

The default CSS theme is getting out of date with today's web standards.
(It for example still contains wonderful things like <!--[if lt IE 9]>).
And I believe it is time for a facelift.

In #844, I started by updating Bootstrap but I have doubts we still really need it as a dependency. The world of CSS is a brighter one these days. Flexbox and grids make positioning convenient, variables and even selector nested are a thing now.
I'm quite confident that we can create a modern stylesheet from scratch that is highly customizable using CSS variables.

Technical

I envision that we revisit _template.html completely:

• Navigation structure
• Mobile menu
• Any Javascript code (for things like the tooltips)

Yet I wouldn't change much of the generated HTML (for the API documentation pages) to start with.

Bet more on:

• Modern CSS (variables, flex and grid, nesting, media queries)
• Light and dark mode out of the box (easily achievable with media queries and variables)
• Modular Javascript (type="module" and ESM import)
• WebComponents (where it makes sense of course)

I don't want to introduce any Node/Deno/Bun like tooling. These are wonderful things but we should stick to modern standards that don't require (any/many) building steps. We want to keep the entry barrier for contributors as low as possible. Having installed only the dotnet SDK should be enough to make some changes.

The theme itself

I wouldn't overly do anything drastic or reinvent the wheel for the theme itself.
We could look at some other documentation sites for reference but I envision something rather basic with a top menu bar, a side menu bar and the page content. Something close to what existing users would expect.

Search

I do notice that search only really works for the API reference pages and also wish to modernize that part.
It is quite common to see searches being handled by third-party solutions like https://www.algolia.com/. These typically have a generous free tier and work really well.

Approach

We probably want to create a separate branch to develop this and publish alphas for people to try out.
At the very least we should ensure:

• FSharp.Core
• FCS
• FSharp.Data
• other projects (please shout if you know good ones)

are well tested.

I've already talked about this topic during the F# for Data Science conference in Berlin with @nhirschey, @kMutagene and @Freymaurer. I'm confident we can make something work here.
And I would be happy to hear your thoughts on this.

[dsyme]

I think it's a great idea!

[nojaf]

I started working on this in branch modern-theme.

All very much WIP.

[nojaf]

Example of how this could look like with some basic theming:

Custom CSS on Telplin side:

@import url('https://fonts.googleapis.com/css2?family=Raleway:ital,wght@0,400;1,300&display=swap');

:root {
    --primary: #ffdd59;
    --secondary: #6d7276;
    --background: #fdfdfd;
    --header-background: var(--primary);
    --system-font: 'Raleway', sans-serif;
    --header-brand-text-transform: capitalize;
    --aside-width:270px;
    --code-background: rgba(210, 222, 222, 0.15);
}

[data-theme=dark] {
    --header-background: var(--secondary);
    --background: #38393a;
    --menu-item-hover-background: #38393a;
}

[nojaf]

One other thing I currently find a bit lacking is the ability to insert a custom script in the head or body of the default template. I find myself often adding one extra script or creating a web component to later use in a Markdown file.

This in itself isn't really a strong or compelling reason to start creating a custom template file. Perhaps we can introduce additional placeholder replacements. Similar to how _menu-template works.

[nojaf]

I've pushed a new feature where you can create a _head.html or _body.html page and the content of that gets inserted into {{fsdocs-head-extra}} and {{fsdocs-body-extra}}.
This is an interesting escape hatch when you want to include some custom HTML without creating your own _template.html from scratch.

Would there be interest in a community call about the progress so far?
Please vote 👍 or 👎 on this message. I'd be happy to showcase some of this work.

[nhirschey]

Some customization of head/body seems nice. Does _body.html go before or after the body? Or is it relative to the location of {{fsdocs-content}}?

I'd like to be able to add automatic download links to each page. To do that, I'd want the below snippet immediately before {{fsdocs-content}} in the default template:

[![Notebook](img/badge-notebook.svg)]({{root}}/{{fsdocs-source-basename}}.ipynb)

The head option is also nice because Plotly.NET graphs ideally have a plotly script in a page header (see plotly/Plotly.NET#373) and I prefer to use the custom template.

[nojaf]

Right now it goes at the end before the closing tag in both cases.
See https://github.com/fsprojects/FSharp.Formatting/blob/b755a513189ba1fc5bc108d92e09c7a01d772a33/docs/_template.html

But people could change this behaviour when they roll their own _template.html.
Although if you were to do that, it is somewhat questionable that you want the _head.html and _body.html.

The scenario for automatic download links to each page would work fine in both _head and _body if you wait for the DOMContentLoaded. I would go for the _body.html in that case.

[Freymaurer]

As it is my first contact with this repo i started with the ##Development section in README.md.

• dotnet fsi build.fsx breaks due to ### Removed, i changed it to **Removed**.

Otherwise dev setup worked! I tested some css stuff in Firefox, edge and opera:

• I really like the default design, looks clean and simple in both light and dark! Just the code blocks look a bit uniform with the current color scheme (at least in light mode).
  
  
  Maybe the colors could have more contrast against each other.
• In edge/opera for a long sidebar and long content we have double scrollbars on the right side. This can be fixed by setting html { overflow: hidden }, while also updating aside { overflow-y: auto; height: calc(100vh - var(--header-height)) } ( height, was prev. min-height). These changes will allow separate scrolling for main content and sidebar, this also removes visual issues with a long sidebar scrolled to the bottom and the main page being static height (this would leave a rather large background area at the main content-area bottom).
  
• In firefox the custom scrollbar is not rendered. Only the html scrollbar. Maybe see here for related info:
  • https://stackoverflow.com/questions/6165472/custom-css-scrollbar-for-firefox/53739309#53739309
  • https://stackoverflow.com/questions/6165472/custom-css-scrollbar-for-firefox/54101063#54101063
    
• No idea if my setup is incomplete but search button does nothing for me, no console output either.
• Maybe add title attribute to navbar elements?
• I actually was not able to find where the sidebar links are generated 😅 Is it possible to nest more than one level? The link to the current page should be highlighted.
• Any ideas for in-page navigation? Should this be handled by the fsdocs user in markdown or should fsdocs provide an additional sidebar option which automatically creates an in-page navigation from existing <h> elements?

[nojaf]

dotnet fsi build.fsx breaks due to ### Removed, i changed it to Removed.

Ah ok, I thought we were using https://github.com/ionide/KeepAChangelog for that but it appears not.
Will update that.

Maybe the colors could have more contrast against each other.

Yes, we can definitely revisit the coding colours. I'm personally not used to dark mode so I struggle there from time to time.

Thanks for testing in firefox/opera/edge. So far I've only used Chrome.

No idea if my setup is incomplete but search button does nothing for me, no console output either.

Yes, search is still on the todo list. It does absolutely nothing right now.

As for the navigation:

Right now the HTML of the navigation is coming from the transformed {{fsdocs-list-of-documents}} and {{fsdocs-list-of-namespaces}}. This is composed by the tool by scanning all the frontmatter data from each file. I would keep that as is for now to be honest. The generated HTML is workable and can be revisited in the next PR.

Maybe add title attribute to navbar elements?

This would require a change in the frontmatter itself. Otherwise, the user has no way of specifying that title.

Is it possible to nest more than one level?
Currently not, that is all rather hard coded. Good suggestion but out of scope.

The link to the current page should be highlighted.

Yes, a fine suggestion but the current information is not present in the generated HTML for this.
Hmm, I might take a shot at this but it will be going down the rabbit hole I fear.

Any ideas for in-page navigation? Should this be handled by the fsdocs user in markdown or should fsdocs provide an additional sidebar option which automatically creates an in-page navigation from existing elements?

I would consider that out of scope as well. I'm open to the idea thought. Do you have any examples where that works nicely?

@Freymaurer many thanks for this feedback! Apologies if I seem unreceptive to some of your ideas; you've pinpointed some of the current tool's weaknesses accurately 😅.

[Freymaurer]

I would consider that out of scope as well. I'm open to the idea thought. Do you have any examples where that works nicely?

• https://bulma.io/documentation/elements/button/#button-addons, not 100% nice, as they put ads in it, which makes it incredibly hard to spot
• https://vitejs.dev/guide/assets.html
• https://lit.dev/docs/components/lifecycle/, i like this design the most as it is easy to spot

Yes, a fine suggestion but the current information is not present in the generated HTML for this.
Hmm, I might take a shot at this but it will be going down the rabbit hole I fear.

I saw you were using lit-webcomponents already and i have actually done something similiar with lit here. Altough this component also reactively updates to scroll position and headers on the page, so a implementation only reflecting the actual url should be way less complex. (Please excuse my ts code 😅 )

[nojaf]

These are great examples, thank you! It really is worth having this.
The only downside is that it would require additional processing to gather that data.
I'm pretty sure we don't have that overview information.

[nhirschey]

Regarding in-page navigation, I think the pytorch docs are pretty good. But overall, it's probably out of scope. It goes from a style change to a wholesale revamp.

The only downside is that it would require additional processing to gather that data. I'm pretty sure we don't have that overview information.

I think we have it in the heading info from the markdown model. The DSL accounts for different heading levels.

The pandoc markdown tool uses that info to generate tables of contents (toc) from section headings. Examples here, specifically demo 2 without toc versus demo 3 with toc, custom css, and custom footer.

[nojaf]

I think we have it in the heading info from the markdown model.

Yes, we have it but it would require some new transformation to HTML and have a new substitution parameter.

Something I think we want to do a bit later maybe.
But again, maybe not. @Freymaurer had some good ideas, maybe to increase the wow factor, we should explorer some of these.

[nojaf]

Another thing that has been on my wish-list for some time is a button that says "Improve this page" and it opens the edit mode of a GitHub page. Again, I'm not sure if we have the information to construct the right URL and not every project is no GitHub but for a lot of folks, this would be nice to have I think.