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

Switching to mdBook #141

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Conversation

noritada
Copy link

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 build

HTML files are generated in the book directory.

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 a cargo test within the _skeptic directory to test the code.

Alternative to !FILENAME

Since mdBook does not seem to have a notation for displaying file names at the beginning of code blocks at this time, I have replaced !FILENAME notations 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.

noritada added 4 commits June 24, 2022 19:53
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.
@noritada noritada marked this pull request as ready for review June 25, 2022 15:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

Consider switching to mdBook
1 participant