Skip to content

Conversation

@Incogdino
Copy link
Contributor

@Incogdino Incogdino commented Apr 14, 2025

  1. List are now left aligned. This ensures that the list numbering is not hidden by custom css style rules and also preserves the indentation of the list elements so that they are reasonably small enough for mobile users.

What is the purpose of this pull request?

  • Documentation update
  • Bug fix
  • Feature addition or enhancement
  • Code maintenance
  • DevOps
  • Improve developer experience
  • Others, please explain:

Closes #2628
Overview of changes:
Updated markbind default list css property list-style-position from outside to inside. This causes the list numbering to be inside the block box rather than outside the block box. More information here

Anything you'd like to highlight/discuss:
The downside(maybe) to this would be that certain list numbering will be slightly misaligned as the number of elements in the list increases. For instance, from number 9 to number 10, the start of content isn't aligned vertically.

image

Screenshot of the CS2103 website on my macOS:
Screenshot 2025-04-14 at 5 58 11 PM

Testing instructions:

Proposed commit message: (wrap lines at 72 characters)

Update list css

  1. List are now left aligned. This ensures that the list numbering is
    not hidden by custom css style rules and also preserves the
    indentation of the list elements so that they are reasonably small
    enough for mobile users.

Checklist: ☑️

  • Updated the documentation for feature additions and enhancements
  • Added tests for bug fixes or features
  • Linked all related issues
  • No unrelated changes

Reviewer checklist:

Indicate the SEMVER impact of the PR:

  • Major (when you make incompatible API changes)
  • Minor (when you add functionality in a backward compatible manner)
  • Patch (when you make backward compatible bug fixes)

At the end of the review, please label the PR with the appropriate label: r.Major, r.Minor, r.Patch.

Breaking change release note preparation (if applicable):

  • To be included in the release note for any feature that is made obsolete/breaking

Give a brief explanation note about:

  • what was the old feature that was made obsolete
  • any replacement feature (if any), and
  • how the author should modify his website to migrate from the old feature to the replacement feature (if possible).

1. List are now left aligned. This ensures that the list numbering is
not hidden by custom css style rules and also preserves the
indentation of the list elements so that they are reasonably small
enough for mobile users.
@codecov
Copy link

codecov bot commented Apr 14, 2025

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 52.80%. Comparing base (da87da1) to head (542e92f).

Additional details and impacted files
@@           Coverage Diff            @@
##           master    #2689    +/-   ##
========================================
  Coverage   52.80%   52.80%            
========================================
  Files         130      130            
  Lines        7162     7162            
  Branches     1503     1480    -23     
========================================
  Hits         3782     3782            
- Misses       3075     3225   +150     
+ Partials      305      155   -150     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@gerteck
Copy link
Member

gerteck commented Apr 17, 2025

Here's a side by side comparison of the effect of changing this style:

  • The indentation of bullet points gets pushed "inside" the bullet content:

image

Sublists:
image

image

Left - New (this PR), Right - Old (master-netlify)

While this fix does indeed solve the issue, I wonder if there is a more stylish way to go about it, as it does increase the indentation substantially...

@Incogdino
Copy link
Contributor Author

Here's a side by side comparison of the effect of changing this style:

  • The indentation of bullet points gets pushed "inside" the bullet content:
    image
    Left - New, Right - Old

While this fix does indeed solve the issue, I wonder if there is a more stylish way to go about it...

This is likely due to the list-style-position property applying to both ordered and unordered lists.

@Incogdino
Copy link
Contributor Author

image

@gerteck I have updated the css style to retain the original positioning for unordered lists.

@gerteck
Copy link
Member

gerteck commented Apr 17, 2025

Thanks for the quick change! Does anyone else have any opinions on the increased indent on the numbered lists?

@damithc
Copy link
Contributor

damithc commented Apr 17, 2025

I'm worried about this indentation disappearing. It affects the readability of the list :-(

image

@tlylt
Copy link
Contributor

tlylt commented Apr 17, 2025

This seems more like a user issue that doesn't need a markbind fix.

I see that the main.css in the 2103 website has

.website-content {
     margin: 12px auto 40px auto;
     max-width: 800px;
     overflow: hidden;
     text-align:justify
 }

which is not contained in our default main.css. The wrapper we provide (for similar effect) is

#content-wrapper {
    flex: 1;
    margin: 0 auto;
    min-width: 0;
    max-width: 1000px;
    overflow-x: auto;
    padding: 0.8rem 20px 0;
    transition: 0.4s;
}

@damithc Adjusting (or removing entirely) the .website-content css should fix the issue. I tested simply removing the overflow-hidden in this custom css and the list issue is gone:

  • to still achieve similar styling, perhaps remove the "website-content" wrapper, and add css directly under content-wrapper. this might be a legacy migration issue
    image

@damithc
Copy link
Contributor

damithc commented Apr 17, 2025

I tested simply removing the overflow-hidden in this custom css and the list issue is gone:

I tried this and it fixed the problem in the list. Thanks for the tip @tlylt 💯

Soon I will try replacing the .website-content entirely.

@Incogdino
Copy link
Contributor Author

image

I think the issue is still relevant here. I tested this with using the markbind userGuide where removing padding defined in main.css using markbind layouts still causes the hundreth place of the list to be missing.

@tlylt
Copy link
Contributor

tlylt commented Apr 17, 2025

I think the issue is still relevant here. I tested this with using the markbind userGuide where removing padding defined in main.css using markbind layouts still causes the hundreth place of the list to be missing.

Why do we need to remove the padding defined in main.css?

@Incogdino
Copy link
Contributor Author

Why do we need to remove the padding defined in main.css?

I was thinking maybe in a case where authors define their own layouts but did not add any padding. With main.css, the numbered lists only gets hidden when the number of items in the list >10k

@tlylt
Copy link
Contributor

tlylt commented Apr 17, 2025

I was thinking maybe in a case where authors define their own layouts but did not add any padding. With main.css, the numbered lists only gets hidden when the number of items in the list >10k

In my opinion it's a known risk that styles might break if users choose to update the default css, any other styling might also break if done incorrectly. Not that there's no need to improve the feature itself, but the approach this PR is going for doesn't resolve the problem nicely without introducing "new problems":

  • list-style-position: inside; styling wise I would prefer to keep it outside, so there's no "misaligned" issue

- Changed ordered list to use browser's table layout
@Incogdino
Copy link
Contributor Author

Incogdino commented Apr 18, 2025

In my opinion it's a known risk that styles might break if users choose to update the default css, any other styling might also break if done incorrectly. Not that there's no need to improve the feature itself, but the approach this PR is going for doesn't resolve the problem nicely without introducing "new problems":

  • list-style-position: inside; styling wise I would prefer to keep it outside, so there's no "misaligned" issue

I agree that keeping styling outside should be preferred as it keeps the alignment of the list elements. Perhaps we can add it as a known issue/ warning to users who are trying to insert custom css stylesheets into their documents?

I also came across this thread on stack overflow where the accepted answer suggested using the browser's table layout algorithm to achieve the same effect. I've tried it out and it does preserve the outside property and keeps the indentation while avoiding the hidden list numbers.

image

I have not found any regressions yet. Have yet to test it out on macOS. @tlylt what do you thhink? I have pushed the commit if you want to try it out.

@tlylt
Copy link
Contributor

tlylt commented Apr 18, 2025

Perhaps we can add it as a known issue/ warning to users who are trying to insert custom css stylesheets into their documents?

i don't see any mention of how custom css can be used in our UG, perhaps we can add some details of that (and the potential pitfalls) in https://markbind-master.netlify.app/userguide/usinghtmljavascriptcss

Regarding the new proposed changes, I have a preference to keep the current simple version as is since the existing layout css works well enough, but thanks @Incogdino for the investigation and finding out the root cause🚀

@Incogdino
Copy link
Contributor Author

i don't see any mention of how custom css can be used in our UG, perhaps we can add some details of that (and the potential pitfalls) in https://markbind-master.netlify.app/userguide/usinghtmljavascriptcss

Regarding the new proposed changes, I have a preference to keep the current simple version as is since the existing layout css works well enough, but thanks @Incogdino for the investigation and finding out the root cause🚀

Okay in that case I shall close this PR and raise an issue to update the documentation

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 this pull request may close these issues.

Numbered lists not showing more than one digit

4 participants