Add mdbook-spec #1520
Merged
Add mdbook-spec #1520
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 preprocessor adds support for several Markdown extensions that should assist with writing.
The next commit will update to keep in sync with the reference.
|
For more context: It is noted that it is not optimal to have |
This link section was already sorted but for a recent change (that understandably probably preferred to keep the diff contained). Let's restore the sort order of the links here.
The CONTRIBUTING guide seems wrapped at 80 character lines. Let's rewrap a paragraph with a line that had overflowed.
Let's follow our own rules in the authoring guide by, e.g., using `---` rather than the Unicode em-dash character, not wrapping lines, specifying the language for code block sections, etc. To improve formatting, we broke out some descriptions that were in code block sections into the main text. We replaced references to "the spec" with "the reference" for consistency, as that's what most of this document uses. And we made some other small editorial improvements.
These two items of style were the only bits present in the style guide and missing from the authoring guide. Let's copy them over, since they are true of the Reference, and this will let us delete the style guide entirely.
The authoring guide now fully incorporates and supersedes the style guide, so let's simply link to that from the style guide.
traviscross
approved these changes
Jul 4, 2024
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.
This adds the use of mdbook-spec for the reference. The intent is to support some extensions that will help with the formatting that we eventually want to add, and to make authoring easier. Most of the changes are described in
authoring.md.This includes several changes split into separate commits. This includes a sync of the authoring document which was over in the rust-lang/spec repo.
This includes some tentative example changes in the CSS, but those will certainly want to change over time (particularly to support different theme colors). These aren't quite being used, yet. The current formatting of the reference should be identical as to before this PR. I will follow up with future PRs to do additional changes, such as removing explicit std links.
This will require some changes in rust-lang/rust in order to work properly, which I will handle before the next book sync.