Switching to mdBook #141
Open
Switching to mdBook #141
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This commit includes only basic configurations.
This commit fixes Rust Playground integrations.
This commit includes notation changes.
This commit works around an issue that mdBook does not have an alternative to the `!FILENAME` notation.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Closes #17.
I migrated the documentation in this repository from GitBook to mdBook as a trial, and the documentation generated using mdBook can be viewed here. The content has not been changed except for the notations. Your feedback would be appreciated.
The motivation for the migration is to make it easier for everyone to generate HTML documents in his/her local environment using a standard document generation system in the Rust world.
How to generate HTML files
% mdbook buildHTML files are generated in the
bookdirectory.Remarks
Rust Playground integrations
With mdBook, code can be executed "directly" within the book instead of in the Playground in a separate window. Users cannot modify the code within the book by default. However, if it is preferable to allow users to modify the code within the book as well, we can set it to be editable.
Testing code inside the book
mdBook provides a command called
mdbook test, which can be used to check the code in the book. However, this feature currently does not allow us to test code using third-party crates easily, it seems to be better for now to continue with the approach of doing acargo testwithin the_skepticdirectory to test the code.Alternative to
!FILENAMESince mdBook does not seem to have a notation for displaying file names at the beginning of code blocks at this time, I have replaced
!FILENAMEnotations with plain Markdown notations.Theme
For now, I am using the default theme provided by mdBook. Of course, it can be customized.
Automatic generation
In the trial site, HTML files are automatically generated and deployed using GitHub Actions as discussed in #7. I have not included automatic generation in this PR for the time being, as I think it is better to separate the topic.