Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Update mdBook theme and improve maintainability #7524

Merged
merged 6 commits into from
Jul 9, 2023

Conversation

zqianem
Copy link
Contributor

@zqianem zqianem commented Jul 3, 2023

Previously, theming Helix's documentation involved making edits to files copied from the default mdBook theme, which would fully override the upstream theme files. This made it difficult to see which theme changes were specific to Helix and prevented any upstream theme fixes from being applied when mdBook updated.

This PR addresses the issue by extracting all of Helix's custom CSS into a dedicated file and removing as many theme files as possible, as recommended by the mdBook docs:

Note: When you override a file, it is possible that you break some functionality. Therefore I recommend to use the file from the default theme as template and only add / modify what you need. You can copy the default theme into your source directory automatically by using mdbook init --theme and just remove the files you don't want to override.

The index.hbs file could not be removed since Helix adds a custom theme; once rust-lang/mdBook#2059 is merged it may be possible. Upstream changes were manually merged instead.

Tested by running mdbook serve under book/ — pages should be pixel-identical to the current docs except for some upstream changes and a fix for layout differences between themes.

@the-mikedavis the-mikedavis added A-documentation Area: Documentation improvements S-waiting-on-review Status: Awaiting review from a maintainer. labels Jul 3, 2023
Copy link
Member

@the-mikedavis the-mikedavis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! I tried serving this and master side-by-side and couldn't tell the difference 👍

@pascalkuthe pascalkuthe merged commit 9a324f3 into helix-editor:master Jul 9, 2023
mtoohey31 pushed a commit to mtoohey31/helix that referenced this pull request Jun 2, 2024
smortime pushed a commit to smortime/helix that referenced this pull request Jul 10, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-documentation Area: Documentation improvements S-waiting-on-review Status: Awaiting review from a maintainer.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants