Skip to content

Improve GitHub Pages rendering#5

Merged
B67687 merged 1 commit intomainfrom
pages/fix-rendering-polish
Apr 9, 2026
Merged

Improve GitHub Pages rendering#5
B67687 merged 1 commit intomainfrom
pages/fix-rendering-polish

Conversation

@B67687
Copy link
Copy Markdown
Owner

@B67687 B67687 commented Apr 9, 2026

What changed

This PR improves the Pages build so the generated site is more readable and more resilient to notebook authoring patterns that were rendering poorly on the live site.

Why it changed

The current Pages output still has a few visible problems:

  • the README homepage can inherit low-contrast text colors from github-markdown-css in some browser theme combinations
  • many notebook pages use \textcolor{...}{...} and related color directives, which either render too faintly on the white page background or break MathJax output entirely
  • at least one notebook contains a markdown table indented under a list item, which exports as raw pipe text instead of a table

User impact

The GitHub Pages site should now:

  • keep dark readable text on the homepage against the white card background
  • render notebook math without washed-out lightgray/darkgray fragments
  • convert the affected logic notebook table into a proper rendered table during export
  • keep notebook tables, inline code, links, and math more readable overall

Implementation notes

  • Added stronger light-theme CSS overrides for generated notebook pages.
  • Added markdown-cell preprocessing before nbconvert runs.
  • The preprocessing unwraps \textcolor{...}{...}, strips \color{...} declarations, and normalizes list-indented markdown table blocks.
  • Preprocessing happens on a temporary copy of the notebook, so source notebooks are not modified during the Pages build.
  • Added explicit homepage color overrides so GitHub-style markdown does not fade out on white backgrounds.

Validation

I validated the preprocessing directly against the affected source notebooks in this repo:

  • discrete-mathematics/logic/if-p-then-q-explained.ipynb
  • discrete-mathematics/series-and-sequences/sum-of-cubes/sum-of-cubes-with-sum-of-squares.ipynb

I also ran a repo-wide sanity check confirming the preprocessing removes all remaining \textcolor / \color{...} directives from exported markdown cell content before conversion.

I could not run a full local Pages build end-to-end in this environment because this machine still has broken local nbconvert template resolution and temp-folder permission issues. The GitHub Actions Pages build on a clean runner is the expected source of truth for final validation.

@B67687 B67687 marked this pull request as ready for review April 9, 2026 13:37
@B67687 B67687 merged commit 186ac32 into main Apr 9, 2026
2 checks passed
@B67687 B67687 deleted the pages/fix-rendering-polish branch April 9, 2026 13:49
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.

1 participant