Reset .markdown-section max-width to 800px

[cippaciong]

Feature request

Reset .markdown-section max-width to 800px or a similar value

Problem or desire

Docsify used to limit articles max-width to 800px but this was changed to 80% in #1017, claiming that such value would look better on wider screens.

As already mentioned by @jhildenbiddle in a comment to that PR, I think this was a mistake since that would negatively affect the readability of the content.

IMO that change lead to two regressions:

• As said, readability becomes much harder on wider screens because line length is definitely too long
• Apparently readability was negatively affected also on smaller screens (e.g. mobile devices) since 80% would introduce unwanted margins in that scenario. See for example this comment and #1273

Proposal

Restore .markdown-section max-width to 800px or a similar value.

Implementation

I'm not an expert, but I should manage to submit a PR if maintainers consider this change acceptable

[jhildenbiddle]

Thanks for filing the issue, @cippaciong.

TL;DR: We can address readability concerns and personal line-length preferences by doing the following:

1. Set the default line length (or "measure") of the markdown area to a font-size relative value that strikes a balance between readability best practices (no more than 80 characters) and aesthetics. After doing a bit of research, this looks to be between 80-95 characters per line which results in a markdown container width of roughly 700px +/- 20px.
2. Allow the markdown container's width to be configurable by site maintainers. This allows sites maintainers and theme authors using a different font to adjust the maximum width as needed to adhere to the "no more than 80 character" line length recommendation.

Details (for those who care)...

Some people will inevitably feel that the new markdown container width looks/feels too narrow. The criticism isn't necessarily wrong. All of the Docsify alternatives I tested have line lengths greater than 80 (see below). Every one of those alternatives also renders both left and right sidebars which help fill the horizontal space. Docsify, by comparison, will have a narrower overall content width which some people may not care for. There are a few additional things we can do to try and reduce (but not eliminate) these concerns:

• Increase the default font size in Docsify's default themes to 16px. Larger font sizes requires a wider markdown container to fit the same number of characters per line. Consider how font size affects the markdown container size when using Source Sans Pro (the web font used in Docsify's vue.css theme):

  Source Sans Pro (used in vue.css)

  • 80 characters @ 16px = 550px container
  • 80 characters @ 15px = 515px container
  • 80 characters @ 14px = 470px container

• Consider alternative fonts that are more visually appealing (wider) at the desired line length. Consider how switching to San Francisco (the default sans-serif font on macOS) affects the markdown container size compared to Source Sans Pro (above):

  San Francisco (macOS)

  • 80 characters @ 16px = 590px container
  • 80 characters @ 15px = 550px container
  • 80 characters @ 14px = 520px container

For comparison, here are the default line length, font size, and content container width values from a few Docsify alternatives:

• Docusaurus: 129 characters @ 16px = 958px
• GitBook: 109 characters @ 16px = 768px
• Starlight: 94 characters @ 16px = 720px
• VitePress: 90 characters @ 16px = 688px

Finally, here are the line lengths using Docsify's vue.css theme and the previous max-width value of 800px:

Source Sans Pro (used in vue.css)

• 16px = 117 characters
• 15px = 125 characters
• 14px = 133 characters

Based on these numbers, reverting the max-width to 800px (#1017) is not our best option. I think the best option is a font-relative max-width value that falls somewhere between 80-90 characters per line @ 16px.

[paulhibbitts]

Thanks @cippaciong for identifying this issue and @jhildenbiddle for the detailed analysis and possible options etc.

In addition to numerical line lengths I think we could consider a few other aspects as well. For example, many folks have grown accustomed to the information density of the current 80% of screen width currently in Docsify (and possibly manually adjust their Browser windows to their liking). In addition, with digital text there are also other aspects coming into play such as the need to scroll to read and how much scrolling is involved etc.

Here is a helpful article that highlights these additional aspects for reference: https://www.roboleary.net/webdev/2023/03/10/ideal-line-length-digital-text.html

I don't think there is an ideal answer to a revised Markdown section width for Docsify, and the current 80% of screen has a lot of readability issues. 800px width may not be ideal either, but given the display of digital text and related aspects, somewhere around there some good candidates might still exist.

[jhildenbiddle]

This issue has been addressed by PR #2469. The changes will be available when Docsify v5 is released.

Once v5 is release, this issue can be resolved by modifying the following theme property:

:root {
  --content-max-width: 72ch;
}