Closed jcbrill closed 2 months ago
Thanks for this detailed outline - this is very helpful in making changes.
However, keep in mind the themes in MM are custom - they are approximate and don't try to necessarily match every feature exactly. Github uses completely different rendering engine than MM does so there will always be some small difference. The theming is approximate.
If somebody wants to take a swipe at matching up the CSS themes that would be great. I'll take a look when I have some spare cycles but it's not high priority on my backlog.
However, keep in mind the themes in MM are custom - they are approximate and don't try to necessarily match every feature exactly. Github uses completely different rendering engine than MM does so there will always be some small difference. The theming is approximate.
The top post could be considered "Much ado about nothing". Feel free to close this issue at any time.
Only recently did I become interested in the MM Github themes due to an issue with a GitHub post containing math-mode color specifications that did not render correctly when using a GitHub dark theme due to my own incorrect assumptions.
As a placeholder, both manual and automatically generated markdown content was using $...\color{black}...$
for the "default" font color which worked fine with light themes but failed miserably with dark themes.
Being able to toggle between the Github light and dark themes in MM prior to posting to GitHub is very useful to me. In some cases, similar issues have arisen with Mermaid diagrams. It is easier to toggle between themes in MM than in GitHub.
For more elaborate styled-posts such as the colored text tables above, my typical iterative workflow is:
When toggling between the MM light and dark themes, the important/critical/warning alert color differences were readily apparent.
The styling differences for alerts between the MM light and dark themes went against my preconceived expectations. I expected the only difference between the MM light and dark themes to be the colors. It is fine if that is not the intent. Expectations adjusted accordingly.
Following the MM documentation suggestion of copying MM preview themes and customizing the copies locally, custom local Github light and dark themes were created and updated for comparison purposes.
The file mm-github-themes.zip
, attached at the end of the top post above, contains:
File | Description |
---|---|
mm-github-themes.md |
Document containing the content of the top post |
PreviewThemes\_Github |
Custom local MM GitHub-like light theme files |
PreviewThemes\_Github Dark |
Custom local MM GitHub-like dark theme files |
The two custom themes, _Github
and _Github Dark
(named with leading underscores so they are at the top of the theme pick list), contain the following changes:
The custom light and dark themes can easily be compared to the MM light and dark themes for content differences. Since css is not in my skill set, the custom themes are more verbose as I do not know an easier way to color the title and left edge of the blockquote and maintain the default font color for the body of the alert text similar to GitHub.
I was reluctant to issue a PR as the custom implementation could be wildly erroneous.
The two custom themes were developed by togging between the MM themes and a browser toggling the appearance between the GitHub default light and dark themes. The methodology is summarized in the two tables below.
Program | Provider | Light | Dark |
---|---|---|---|
MM | MM | Github |
Github Dark |
MM | Custom | _Github |
_Github Dark |
Browser | GitHub | Default Light |
Default Dark |
Program | Provider | Document | Mode | Theme |
---|---|---|---|---|
MM | MM | mm-github-themes.md |
Light | Github |
MM | Custom | mm-github-themes.md |
Light | _Github |
Browser | GitHub | top post of thread | Light | Light Default |
MM | MM | mm-github-themes.md |
Dark | Github Dark |
MM | Custom | mm-github-themes.md |
Dark | _Github Dark |
Browser | GitHub | top post of thread | Dark | Dark Default |
Again, feel free to close at any time.
I actually did take a look at this and made some changes to the GitHub Dark theme to start with:
Took a bit of tweaking of the style sheet, and this has to be migrated over to all the other default styles and adjusted for colors. In the process also updated FontAwesome library to v6 so that we can match the icons more closely (ie. using 'regular' style icons, instead of 'solid').
However, the colors that are actually used by GitHub don't match the colors you have in your table. I used the actual GitHub colors. Some things don't appear to work - like [!INFO]
.
That looks great!
However, the colors that are actually used by GitHub don't match the colors you have in your table. I used the actual GitHub colors.
Likely user error then.
The computed rbg values for the GitHub default light/dark theme entities reported by chrome may have been used in some cases. Perhaps local configurations of system/github, etc affected methodology used.
Some things don't appear to work - like [!INFO].
It's always something with Github markdown.
Those tags originally were DocFX tags, so [!INFO]
might just not be supported, but is in the original DocFX spec. Certainly is a useful feature either way and I'm glad they added this.
Now I have to fix all the other themes as the styling has changed. Luckily it's mostly cut and paste and then adjusting the colors and these base colors should actually work for all backgrounds (or at least match the light and dark versions). At least with non-GitHub themes I won't have to match anything exactly :smile:
And here is the light theme:
Not sure I understand this comment:
As a placeholder, both manual and automatically generated markdown content was using
$...\color{black}...$
for the "default" font color which worked fine with light themes but failed miserably with dark themes.
The changes to both the light and dark themes are very well done. Kudos.
Not sure I understand this comment:
As a placeholder, both manual and automatically generated markdown content was using
$...\color{black}...$
for the "default" font color which worked fine with light themes but failed miserably with dark themes.
That is because it is not very well written.
Examples using math-mode colored text:
$\color{red}\text{always red}$
is: $\color{red}\text{always red}$.$\color{black}\text{always black}$
is: $\color{black}\text{always black}$.$\color{}\text{the default color}$
is: $\color{}\text{the default color}$.$\text{the default color}$
is: $\text{the default color}$.The always black
black text at the end of item 2 "disappears" when using the GitHub default dark theme (i.e., black text on a black background).
This seems obvious after-the-fact. The fatal flaw was assuming that black text would always be correct. I was erroneously using the color black
by assuming black was always close enough to the default text color which was a bad assumption.
Forcing colors that are too light are a problem with the light themes. Forcing colors that are too dark are a problem with the dark themes. The challenge is finding the Goldilocks ranges of colors that work well for both light and dark themes.
The rendered colors for the
[!IMPORTANT]
,[!WARNING]
, and[!CAUTION]
alerts in theGithub Dark
theme appear to be incorrect. See Table 1 below.Markdown Monster \ Version 3.3.6 \ June 15, 2024 \ 64-bit, .NET 8.0.5
The content of this post and two custom GitHub themes (i.e.,
_Github
and_Github Dark
) are contained in the attached zip file.The rendered objects for alerts differ between the
Github
andGithub Dark
themes:Github
theme.Github Dark
theme.The alert colors in the MM
Github
and MMGithub Dark
themes are significantly different from the colors employed in the GitHubLight Default
and GitHubDark Default
themes. See Table 1 below.Github appears to render alerts similar to blockquotes with the exception that the body text is rendered using the default text color rather than the alert color.
The attached markdown document and themes can be used to compare the MM GitHub themes (i.e.,
_Github
,_Github Dark
,Github
, andGithub Dark
) with the default GitHub themes (i.e.,Light Default
andDark Default
)Table 2 and Table 3 below contain more of the color definitions employed by MM and Github for the light and dark themes, respectively.
Notes:
Aside:
Disclaimer:
Feel free to ignore.
Table 1 Rendered Alert Titles and Colors - MM vs GitHub
Example 1 - Blockquote and Alerts
Table 2 Rendered Colors - MM Github vs GitHub Light Default
Table 3 Rendered Colors - MM Github Dark vs GitHub Dark Default
mm-github-themes.zip