[dalance]

This PR documents how to implement custom playgrounds.

This is a successor to PR #2286.
The method described in #2286 is no longer available in v0.5, so it has been rewritten for v0.5, and
it was possible to implement it with fewer patches than the previous version.

Related: #350 #1453 #1759

[GuillaumeGomez]

Sorry for the delay, we now have an mdbook team so things should move a bit faster here. This sounds like a very good idea to add an example! Do you mind adding a GUI test to ensure that the code you provided won't become outdated when we make updates?

[GuillaumeGomez]

Need a GUI test using the JS code example to ensure it doesn't become outdated.

View changes since this review

[rustbot]

Reminder, once the PR becomes ready for a review, use @rustbot ready.

[dalance]

Thank you for your review.
I'm glad the mdBook team has been established.

When I wrote this documentation, I understood that review bandwidth was extremely limited,
so I wrote a procedure which can be implemented without making changes to mdBook itself.

If minor changes are acceptable, I can clean up some of the JavaScript hacks, what do you think?
For example, if we slightly adjusted the condition at

mdBook/crates/mdbook-html/src/html/tree.rs

Line 1010 in 74b14bb

if !is_playground {

,
the section titled "Restrict the .playground selector to <pre>" will no longer be necessary.

[GuillaumeGomez]

If that can make things simpler, then it's worth a try!

[dalance]

I wrote 2 issues to improve custome playground support.
If both of them are accepted, the way of this PR is significantly simplified because theme override is not necessary.
Especially it is important that book.js override is not necessary because it causes manual synchronization to mdBook update.

[dalance]

@GuillaumeGomez
I created #3218.

Regarding #3216, since it would have a bit large impact, such as requiring the addition of a configuration value,
I'd like to prepare it only after reaching a certain level of consensus.
What do you think?

If there is no prospect of it being accepted in the short term, I am also open to rewriting this guide on the assumption that #3216 can't be used.

[dalance]

I created #3241.

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[dalance]

@GuillaumeGomez
Thank you for your review and merge for #3215 and #3216.
I updated the guide and added a GUI test.

[GuillaumeGomez]

Can we include a file directly? That would allow:

1. To not duplicate content between here and the GUI test.
2. Prevent this one to become outdated.

View changes since the review

[GuillaumeGomez]

Suggested change

	```
	```text

View changes since the review

[GuillaumeGomez]

Suggested change

	var oop = require("../lib/oop");
	var TextMode = require("./text").Mode;
	var TextHighlightRules = require("./text_highlight_rules").TextHighlightRules;
	var Rules = function() {
	this.$rules = { start: [{ token: "keyword", regex: "\\bprint\\b" }] };
	};
	oop.inherits(Rules, TextHighlightRules);
	var Mode = function() { this.HighlightRules = Rules; };
	const oop = require("../lib/oop");
	const TextMode = require("./text").Mode;
	const TextHighlightRules = require("./text_highlight_rules").TextHighlightRules;
	const Rules = function() {
	this.$rules = { start: [{ token: "keyword", regex: "\\bprint\\b" }] };
	};
	oop.inherits(Rules, TextHighlightRules);
	const Mode = function() { this.HighlightRules = Rules; };

View changes since the review

[GuillaumeGomez]

Need to apply the suggested changes below. One more argument in favour of including a file rather than duplicating content. :)

View changes since the review