Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Modernize the default theme #849

Closed
nojaf opened this issue Oct 6, 2023 · 37 comments · Fixed by #861
Closed

Modernize the default theme #849

nojaf opened this issue Oct 6, 2023 · 37 comments · Fixed by #861

Comments

@nojaf
Copy link
Collaborator

nojaf commented Oct 6, 2023

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
Copy link
Contributor

dsyme commented Oct 10, 2023

I think it's a great idea!

@nojaf
Copy link
Collaborator Author

nojaf commented Oct 16, 2023

I started working on this in branch modern-theme.

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

All very much WIP.

@nojaf
Copy link
Collaborator Author

nojaf commented Oct 17, 2023

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

image

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
Copy link
Collaborator Author

nojaf commented Oct 17, 2023

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
Copy link
Collaborator Author

nojaf commented Oct 23, 2023

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
Copy link
Collaborator

nhirschey commented Oct 23, 2023

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
Copy link
Collaborator Author

nojaf commented Oct 23, 2023

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
Copy link

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).
    image
    image
    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).
    image
  • In firefox the custom scrollbar is not rendered. Only the html scrollbar. Maybe see here for related info:
  • 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
Copy link
Collaborator Author

nojaf commented Oct 24, 2023

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
Copy link

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?

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
Copy link
Collaborator Author

nojaf commented Oct 24, 2023

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
Copy link
Collaborator

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
Copy link
Collaborator Author

nojaf commented Oct 24, 2023

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
Copy link
Collaborator Author

nojaf commented Oct 26, 2023

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
Copy link
Collaborator Author

nojaf commented Oct 30, 2023

@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.

image

@Freymaurer
Copy link

Nice! Can you show me where you implemented this?

@nojaf
Copy link
Collaborator Author

nojaf commented Oct 31, 2023

Everything is still happening in the modern theme branch.
See ff85571

@nojaf nojaf pinned this issue Nov 1, 2023
@nojaf
Copy link
Collaborator Author

nojaf commented Nov 2, 2023

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
Copy link
Contributor

oh wow, this is shaping up really nice!

@nojaf
Copy link
Collaborator Author

nojaf commented Nov 3, 2023

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 nojaf linked a pull request Nov 3, 2023 that will close this issue
@nojaf
Copy link
Collaborator Author

nojaf commented Nov 3, 2023

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

@Freymaurer
Copy link

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

@TheAngryByrd
Copy link

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
Copy link
Collaborator

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

image

@Freymaurer
Copy link

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.

image

@nojaf
Copy link
Collaborator Author

nojaf commented Nov 7, 2023

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
Copy link
Collaborator

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

  1. Default search uses fuse.js provided by Boostrap-5.
  2. 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
Copy link
Collaborator Author

nojaf commented Nov 8, 2023

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

@nhirschey
Copy link
Collaborator

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
Copy link
Collaborator

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.

image

@nojaf
Copy link
Collaborator Author

nojaf commented Nov 9, 2023

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
Copy link
Collaborator Author

nojaf commented Nov 9, 2023

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
Copy link
Collaborator

nhirschey commented Nov 13, 2023

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
Copy link

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

@nojaf
Copy link
Collaborator Author

nojaf commented Nov 14, 2023

Good catch, I'll go with confused.

image

@smoothdeveloper
Copy link

smoothdeveloper commented Nov 14, 2023

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.

image

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):

image

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
Copy link
Collaborator Author

nojaf commented Nov 15, 2023

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/.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

7 participants