Modernize the default theme

nojaf commented 9 months ago

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 https://github.com/fsprojects/FSharp.Formatting/pull/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 commented 8 months ago

I think it's a great idea!

nojaf commented 8 months ago

I started working on this in branch modern-theme.

fsharp-formatting-light fsharp-core-theme-dark

All very much WIP.

nojaf commented 8 months ago

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 commented 8 months ago

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 commented 8 months ago

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 :-1: on this message. I'd be happy to showcase some of this work.

nhirschey commented 8 months ago

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 https://github.com/plotly/Plotly.NET/issues/373) and I prefer to use the custom template.

nojaf commented 8 months ago

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 commented 8 months ago

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 commented 8 months ago

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 commented 8 months ago

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 commented 8 months ago

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 commented 8 months ago

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 commented 8 months ago

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 commented 8 months ago

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.

nojaf commented 8 months ago

@Freymaurer I was able to add a CSS class to the currently active menu item. This was quite the hackery for sure and won't work when you are viewing API references.

Freymaurer commented 8 months ago

Nice! Can you show me where you implemented this?

nojaf commented 8 months ago

Everything is still happening in the modern theme branch. See https://github.com/fsprojects/FSharp.Formatting/commit/ff8557156f03cc2268f5507c103364918630869b

nojaf commented 8 months ago

page-content-bar

I added the "On this page" section. Very happy with the result, a little less with how I got there. This works but again isn't super ideal. I have to process the generated html to construct this. There is a limitation in the Markdown data, it doesn't contain the generated id in the anchor for the heading.

I will publish the first alpha of this tomorrow. I'm at the stage where I changed a lot of things and no longer can say whether this will still work in every situation.

kMutagene commented 8 months ago

oh wow, this is shaping up really nice!

nojaf commented 8 months ago

You can play with this using https://www.nuget.org/packages/fsdocs-tool/20.0.0-alpha-001

Be aware that there are gaps. Let me know how things are going.

nojaf commented 8 months ago

Live example: https://ionide.io/FSharp.Analyzers.SDK/

Freymaurer commented 8 months ago

Looks very nice 👍 One minor thing. In darkmode contrast on "active page" is rather low, maybe adjust the colors a bit

TheAngryByrd commented 8 months ago

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.

I was able to achieve that in IcedTasks:

        <div class="float-right" id="edit-this-page"><span><a class="nav-link"
                    href="{{fsdocs-package-project-url}}edit/{{fsdocs-repository-branch}}/docsSrc/{{fsdocs-source-filename}}"><i
                        class="fa-regular fa-pen-to-square pe-2"></i>Edit this page</a></span></div>

nhirschey commented 7 months ago

The tooltips with modern theme are running off the page. I think the old tooltips were left-aligned with the token the tooltip was for. Maybe the tooltip is now center aligned? See when I hover over List or sortBy in the below gif. The tooltip for DateTime is also pretty bad (bottom screenshot). See the live version here.

tooltip

Freymaurer commented 7 months ago

For me it looks alright, tested in Firefox, Opera and Edge. But i think the intellisense should have a max-width and max-height setting with overflow: scroll.

nojaf commented 7 months ago

There is some new code to place the tooltip on the top when it can't fit on the rest of the screen. But I think it indeed could benefit from max-width and max-height.

nhirschey commented 7 months ago

Regarding better search, I investigated pkgdown (=FSharp.Formatting for the R ecosystem). Search configuration page here.

Default search uses fuse.js provided by Boostrap-5.
For better search they incorporate Algolia, with some config required.

So once again, Algolia is the industry standard. But personally, I like a simple, zero-config search option as the default.

nojaf commented 7 months ago

Yes, for v20 we should incorporate something like fuse.js (replacing lunr). Afterwards, Algolia can be investigated.

nhirschey commented 7 months ago

The tooltips with modern theme are running off the page.

nhirschey

For me it looks alright, tested in Firefox, Opera and Edge. -Freymaurer

Ok, I found the problem. Tooltips in edge run off the page with "vertical tabs" turned on. If I turn off vertical tabs and use traditional horizontal browser tabs then it looks good.

Vertical tabs	Horizontal tabs

nhirschey commented 7 months ago

The menu items are not scrollable for me on mobile safari. Moving my fingers where these red arrows are in the screenshot doesn’t scroll to show me for example the API menu item.

nojaf commented 7 months ago

Good catch, that was indeed not working yet.

Released https://www.nuget.org/packages/fsdocs-tool/20.0.0-alpha-005

20.0.0-alpha-005 - 2023-11-09

Changed

Improve API doc styling.

Fixed

Make mobile menu scrollable.

nojaf commented 7 months ago

Released https://www.nuget.org/packages/fsdocs-tool/20.0.0-alpha-006

20.0.0-alpha-006 - 2023-11-09

Added

Revisited search using fusejs

This version has a basic search. I tweaked things a bit on this indexer side. It still isn't perfect, but I hope it works well enough.

nhirschey commented 7 months ago

It's really looking good @nojaf.

I like a lot of what's new, but one thing I don't like is the new blockquote style. To me it looks like code rather than text. I'd prefer that the style was closer to normal text style, but maybe it's just me.

I pushed a test site at this link with different block quote styles. The styles are identified with reaction emojis so people can vote by reacting to this post with the relevant emoji. My preference is something similar to 😕.

Freymaurer commented 7 months ago

I would go for 😕 , but with a border-radius: unset, so we get clear cut corners.

nojaf commented 7 months ago

Good catch, I'll go with confused.

smoothdeveloper commented 7 months ago

the nits for me so far:

the dark background for code samples is too bright / gives poor contrast for reading the code, and maybe the plain background out of code samples, a bit too dark.

suggested code coloring tweaks in dark theme:

--code-background: #28282D;
--code-function2-color: #cbda9d;
--code-value-color: #ffb4e9;
--code-reference-color: #40fddd;
--code-strings-color: #86b4b9;
--code-comment-color: #84d16e;

which looks like this (https://ionide.io/FSharp.Analyzers.SDK/content/Getting%20Started%20Writing.html):

Might be worth, in context of this repository, to have a F# code sample that lights up all colors the F# semantic analysis supports, and with some fable/js magic, a theme picker, we can then consider supporting shipping color schemes for code.

edit: the overall make-up is stellar, it incentivizes me to look at updating some repository to fsdocs of today.

nojaf commented 7 months ago

Released

20.0.0-alpha-010 - 2023-11-15

Fixed

Update styling for blockquote.
Update search documentation.
Tweak dark theme colors.
Loosen the header link search restriction.
Improve custom theme icon.
Correct fsdocs-menu-item-active-class value.
Fix example of Right-Side navigation.

This is the version I used to tweak https://fsprojects.github.io/fantomas/docs/.

fsprojects / FSharp.Formatting