Auto upgrade `main.css` file in MarkBind sites for new releases

[jonahtanjz]

Please confirm that you have searched existing issues in the repo

Yes, I have searched the existing issues

Any related issues?

#581

What is the area that this feature belongs to?

Author Usability, DevOps

Is your feature request related to a problem? Please describe.

When users run markbind init, a standard main.css file is created. However, this file remains the same even after users have upgraded their MarkBind version. Any new changes introduced to the main.css file will not be reflected on their end. Users will have to manually add/edit the css file to get any bugfixes or be able to use new features on their existing MarkBind sites (Both #1692 and #1939 are good examples of having to manually edit the css file).

Describe the solution you'd like

Should we remove the main.css file entirely from the template site and shift all the existing css to markbind.css? This way, we can easily control the css for existing MarkBind sites so any bugfixes and new features can work out of the box after MarkBind is upgraded.

Describe alternatives you've considered

Have a command like markbind upgrade to pull in the new changes to the existing main.css file. However this will be tricky as users may have edited the main.css file and may overwrite their existing css.

@MarkBind/active-devs What do you all think about this?

[tlylt]

Should we remove the main.css file entirely from the template site and shift all the existing css to markbind.css? This way, we can easily control the css so any bugfixes and features can work out of the box when MarkBind is upgraded.

Agree with the pros of this approach, perhaps one disadvantage that I can think of is that this may make customizing the site's stylesheet slightly harder? Currently, with the main.css, it might be easier if anyone wants to make some quick adjustments to the default style. Without it, then a user may have to spend more time finding out what CSS selector to use, etc.

Have a command like markbind upgrade to pull in the new changes to the existing main.css file. However this will be tricky as users may have edited the main.css file and may overwrite their existing CSS.

I think this is a viable alternative solution. For the tricky part, I feel that giving a warning(or we first document the caveat and link to it in our warning) is a reasonable compromise. If a user has edited the CSS, it might be necessary anyway, for the user to adjust their stylesheet even if there's no visible conflict between the new main.css and his/her edited main.css (maybe the styles themselves are in conflict)

[ang-zeyu]

Should we remove the main.css file entirely from the template site and shift all the existing css to markbind.css?

I believe layout styles should stay in user land where they matter, it wouldn't make much sense to globally apply the layout styles if the layouts are changed by the user / different from the start (e.g. minimal template).

Also the point above on making changes being not as easy #1961 (comment)

I've actually discussed this with @damithc back in the past, we thought it'd be ok at that time. (coming from an old, controlled layout system comprised of numerous files (header, navigation, page layout, page, ...)).
I'm not sure now looking back how inconvenient it is though. (ping @damithc)

My thoughts currently are that:

• since we assume users have some css knowledge (and they probably do if they're modifying main.css)
• we should communicate how to perform these breaking changes clearly in the release notes
• ➕ breaking changes don't come often
• ➕ might modify the html layouts themselves, which may also contain breaking changes (e.g. sticky header). Wouldn't make too much sense to bundle in main.css changes but not somehow the html layout's too. (point being not too easy to migrate regardless)

I think this is a viable alternative solution.

+1

Though, pointing out there's also which template's main.css to consider (and if we want to support more templates). It might get awkward if you have to do markbind givememaincss --template minimal (if you even remember the template you started with =P)

Just some random ideas:

• perhaps we could store the template information (but old sites wouldn't have that) somewhere on markbind init.
• or diff the css files to figure out which template
  • this would also probably be able to detect any user modifications
• present the diff? 👀 (again, not sure which template's though)
• shift back to the old layout system? 👀 @damithc

[ang-zeyu]

For reference the old layout system looked roughly like this iirc:

_markbind
  layouts
    mylayout1
      page.md - like our current layouts, but only for the page structure (middle / main content container)
      header.md - didn't naturally support sticky announcement bars. We still could of course
      footer.md
      navigation.md - site nav
      pagenav needed to be specified somewhere else, can't recall =(
      .css files
      .js files
    mylayout2
      repeat ...
    mylayout3
      repeat ...
    mylayout4
      repeat ...
    headers
      ... more headers here that could individually override each page's header ...
    footers
      ... more footers here that could individually override each page's header ...
    navigation
      ... more site navs here that could individually override each page's header ...

TLDR

• lots of files, and possibly repeated ones (<include /> mechanisms didn't work back then in layouts too, it should be fixable, so less repeated content - but still lots of files)
• controlled structure

[damithc]

I haven't done the v4 migration yet -- will see how the actual migration effort is.

Would something like the below help?
When the user runs any markbind command, detect if the user has done an upgrade and inform the user the latest release contains breaking changes (with a link to see instructions on how to upgrade), and wait for user to type 'yes'.

Some target users (e.g., instructors using MarkBind for creating course websites) might not know CSS while some (e.g., devs using MarkBind for project documentation) might. Ideally, the user should be able to survive without any CSS knowledge, but having CSS knowledge should allow the user to go beyond basic usage.

[ang-zeyu]

Would something like the below help?

It's not possible right now unfortunately as we don't store the MarkBind build version. =(

Regardless,

Some target users (e.g., instructors using MarkBind for creating course websites) might not know CSS while some (e.g., devs using MarkBind for project documentation) might

In this sense, while it offers more flexibility (and less files), I'm starting to think the V3 layouts system shift might have been a misstep.

We've come across several "awkward" places where css/html knowledge is almost-required with the layout system shift

• sticky headers
• sticky behaviour
• how the mobile site / page nav buttons pulls things inside
• this issue

On a brighter note... some things the shift enabled:

• flexibility: sticky announcement bar, left sticky sidebar, right sidebar, ...
  • although the use case might be mote if we assume most users have little to no css knowledge
• much fewer files to keep track of

Perhaps we should be shifting back to the old structured system partially in some way, while trying to keep the number of files down. It's quite a nuclear option, one I don't think anyone here is able to attempt anytime soon.

In the meantime, I suggest simply making the release notes instructions as clear as possible:

• present a automatic github diff for the layout file and css file, explain each logical change in there https://github.com/MarkBind/markbind/compare/v3.0.0...markbind:v4.0.0?diff=unified
  • packages/core/template/default/_markbind/layouts/default.md
  • packages/core/template/default/stylesheets/main.css
  • I see a manual one for the stylesheet is already in the release notes, an automatic diff should make things easier (cc @jonahtanjz)
• link to the release stylesheet https://github.com/MarkBind/markbind/blob/96530543d0cfd7b1a386e13f069234afae8c39de/packages/core/template/default/stylesheets/main.css so users who don't have css knowledge can copy-paste all changes directly
  • note again this isn't perfect since the html layout file (which is coupled to the stylesheet changes) might have been edited (unless we're assuming users don't have html knowledge as well which seems unlikely)

[damithc]

As we don't have a wide user base yet, it is fine to experiment, and back-track when needed. Yes, most likely a mid-way solution might be the way to go in the end. Nevertheless, we can also try to make the best of the current approach (rather than do a major back-track) to see if we can make it workable for both types of users.

Would something like the below help?

It's not possible right now unfortunately as we don't store the MarkBind build version. =(

Yup, possibly we can build that capability in for the future releases.

link to the release stylesheet https://github.com/MarkBind/markbind/blob/96530543d0cfd7b1a386e13f069234afae8c39de/packages/core/template/default/stylesheets/main.css so users who don't have css knowledge can copy-paste all changes directly

• note again this isn't perfect since the html layout file (which is coupled to the stylesheet changes) might have been edited (unless we're assuming users don't have html knowledge as well which seems unlikely)

Good point. I think we can safely assume that CSS-ignorant users are unlikely to modify CSS/layout files that much.

[ang-zeyu]

Made a ticket for considering shifting back to a more restrictive layout system.

My thoughts currently are that:

This is only a short term solution.