Skip to content

Commit 7108314

Browse files
ehussehuss
authored
Merge pull request #2875 from ehuss/0.5-alpha.1-changelog
Add 0.5 migration guide
2 parents 7eb63bf + 283b279 commit 7108314

File tree

1 file changed

+210
-0
lines changed

1 file changed

+210
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,215 @@
11
# Changelog
22

3+
### 0.5 Migration Guide
4+
5+
During the pre-release phase of the 0.5 release, the documentation may be found at <https://rust-lang.github.io/mdBook/pre-release/>.
6+
7+
The 0.5 release contains several breaking changes from the 0.4 release. Preprocessors and renderers will need to be migrated to continue to work with this release. After updating your configuration, it is recommended to carefully compare and review how your book renders to ensure everything is working correctly.
8+
9+
If you have overridden any of the theme files, you will likely need to update them to match the current version.
10+
11+
The following is a summary of the changes that may require your attention when updating to 0.5:
12+
13+
#### Config changes
14+
15+
- Unknown fields in config are now an error.
16+
[#2787](https://github.com/rust-lang/mdBook/pull/2787)
17+
[#2801](https://github.com/rust-lang/mdBook/pull/2801)
18+
- Removed `curly-quotes`, use `output.html.smart-punctuation` instead.
19+
[#2788](https://github.com/rust-lang/mdBook/pull/2788)
20+
- Removed `output.html.copy-fonts`. The default fonts are now always copied unless you override the `theme/fonts/fonts.css` file.
21+
[#2790](https://github.com/rust-lang/mdBook/pull/2790)
22+
- If the `command` path for a renderer or preprocessor is relative, it is now always relative to the book root.
23+
[#2792](https://github.com/rust-lang/mdBook/pull/2792)
24+
[#2796](https://github.com/rust-lang/mdBook/pull/2796)
25+
- Added the `optional` field for preprocessors. The default is `false`, so this also means it is an error by default if the preprocessor is missing.
26+
[#2797](https://github.com/rust-lang/mdBook/pull/2797)
27+
- `output.html.smart-punctuation` is now `true` by default.
28+
[#2810](https://github.com/rust-lang/mdBook/pull/2810)
29+
- `output.html.hash-files` is now `true` by default.
30+
[#2820](https://github.com/rust-lang/mdBook/pull/2820)
31+
- Removed support for google-analytics. Use a theme extension (like `head.hbs`) if you need to continue to support this.
32+
[#2776](https://github.com/rust-lang/mdBook/pull/2776)
33+
- Removed the `book.multilingual` field. This was never used.
34+
[#2775](https://github.com/rust-lang/mdBook/pull/2775)
35+
- Removed the very old legacy config support. Warnings have been displayed in previous versions on how to migrate.
36+
[#2783](https://github.com/rust-lang/mdBook/pull/2783)
37+
38+
#### Theme changes
39+
40+
- Replaced the `{{#previous}}` and `{{#next}}` handlebars helpers with simple objects that contain the previous and next values.
41+
[#2794](https://github.com/rust-lang/mdBook/pull/2794)
42+
- Removed the `{{theme_option}}` handlebars helper. It has not been used for a while.
43+
[#2795](https://github.com/rust-lang/mdBook/pull/2795)
44+
45+
#### Rendering changes
46+
47+
- Updated to a newer version of `pulldown-cmark`. This brings a large number of fixes to markdown processing.
48+
[#2401](https://github.com/rust-lang/mdBook/pull/2401)
49+
- The font-awesome font is no longer loaded as a font. Instead, the corresponding SVG is embedded in the output for the corresponding `<i>` tags. Additionally, a handlebars helper has been added for the `hbs` files.
50+
[#1330](https://github.com/rust-lang/mdBook/pull/1330)
51+
- Changed all internal HTML IDs to have an `mdbook-` prefix. This helps avoid namespace conflicts with header IDs.
52+
[#2808](https://github.com/rust-lang/mdBook/pull/2808)
53+
- There is a new internal HTML rendering pipeline. This is primarily intended to give mdBook more flexibility in generating its HTML output. This resulted in some small changes to the HTML structure. HTML parsing may now be more strict than before.
54+
[#2844](https://github.com/rust-lang/mdBook/pull/2844)
55+
- Links on the print page now link to elements on the print page instead of linking out to the individual chapters.
56+
[#2844](https://github.com/rust-lang/mdBook/pull/2844)
57+
- Added support for definition lists. These are enabled by default, with the option `output.html.definition-lists` to disable it.
58+
[#2847](https://github.com/rust-lang/mdBook/pull/2847)
59+
- Added support for admonitions. These are enabled by default, with the option `output.html.admonitions` to disable it.
60+
[#2851](https://github.com/rust-lang/mdBook/pull/2851)
61+
62+
#### CLI changes
63+
64+
- Removed the `--dest-dir` option to `mdbook test`. It was unused since `mdbook test` does not generate output.
65+
[#2805](https://github.com/rust-lang/mdBook/pull/2805)
66+
- Changed CLI `--dest-dir` to be relative to the current directory, not the book root.
67+
[#2806](https://github.com/rust-lang/mdBook/pull/2806)
68+
69+
#### Rust API
70+
71+
- The Rust API has been split into several crates ([#2766](https://github.com/rust-lang/mdBook/pull/2766)). In summary, the different crates are:
72+
- `mdbook` — The CLI binary.
73+
- [`mdbook-driver`](https://docs.rs/mdbook-driver/latest/mdbook_driver/) — The high-level library for running mdBook, primarily through the `MDBook` type. If you are driving mdBook programmatically, this is the crate you want.
74+
- [`mdbook-preprocessor`](https://docs.rs/mdbook-preprocessor/latest/mdbook_preprocessor/) — Support for implementing preprocessors. If you have a preprocessor, then this is the crate you should depend on.
75+
- [`mdbook-renderer`](https://docs.rs/mdbook-renderer/latest/mdbook_renderer/) — Support for implementing renderers. If you have a custom renderer, this is the crate you should depend on.
76+
- [`mdbook-markdown`](https://docs.rs/mdbook-markdown/latest/mdbook_markdown/) — The Markdown renderer. If you are processing markdown, this is the crate you should depend on. This is essentially a thin wrapper around `pulldown-cmark`, and re-exports that crate so that you can ensure the version stays in sync with mdBook.
77+
- [`mdbook-summary`](https://docs.rs/mdbook-summary/latest/mdbook_summary/) — The `SUMMARY.md` parser.
78+
- [`mdbook-html`](https://docs.rs/mdbook-html/latest/mdbook_html/) — The HTML renderer.
79+
- [`mdbook-core`](https://docs.rs/mdbook-core/latest/mdbook_core/) — An internal library that is used by the other crates for shared types. You should not depend on this crate directly since types from this crate are rexported from the other crates as appropriate.
80+
- Changes to `Config`:
81+
- [`Config::get`](https://docs.rs/mdbook-core/latest/mdbook_core/config/struct.Config.html#method.get) is now generic over the return value, using `serde` to deserialize the value. It also returns a `Result` to handle deserialization errors. [#2773](https://github.com/rust-lang/mdBook/pull/2773)
82+
- Removed `Config::get_deserialized`. Use `Config::get` instead.
83+
- Removed `Config::get_deserialized_opt`. Use `Config::get` instead.
84+
- Removed `Config::get_mut`. Use `Config::set` instead.
85+
- Removed deprecated `Config::get_deserialized_opt`. Use `Config::get` instead.
86+
- Removed `Config::get_renderer`. Use `Config::get` instead.
87+
- Removed `Config::get_preprocessor`. Use `Config::get` instead.
88+
- Public types have been switch to use the `#[non_exhaustive]` attribute to help allow them to change in a backwards-compatible way.
89+
[#2779](https://github.com/rust-lang/mdBook/pull/2779)
90+
[#2823](https://github.com/rust-lang/mdBook/pull/2823)
91+
- Changed `MDBook` `with_renderer`/`with_preprocessor` to overwrite the entry if an extension of the same name is already loaded. This allows the caller to replace an entry.
92+
[#2802](https://github.com/rust-lang/mdBook/pull/2802)
93+
- Added `MarkdownOptions` struct to specify settings for markdown rendering for `mdbook_markdown::new_cmark_parser`.
94+
[#2809](https://github.cocm/rust-lang/mdBook/pull/2809)
95+
- Renamed `Book::sections` to `Book::items`.
96+
[#2813](https://github.com/rust-lang/mdBook/pull/2813)
97+
- `mdbook::book::load_book` is now private. Instead, use one of the `MDBook` load functions like `MDBook::load_with_config`.
98+
- Removed `HtmlConfig::smart_punctuation` method, use the field of the same name.
99+
- `CmdPreprocessor::parse_input` moved to `mdbook_preprocessor::parse_input`.
100+
- `Preprocessor::supports_renderer` now returns a `Result<bool>` instead of `bool` to be able to handle errors.
101+
- Most of the types from the `theme` module are now private. The `Theme` struct is still exposed for working with themes.
102+
- Various functions in the `utils::fs` module have been removed, renamed, or reworked.
103+
- Most of the functions in the `utils` module have been moved, removed, or made private.
104+
105+
## mdBook 0.5.0-alpha.1
106+
[v0.4.52...v0.5.0-alpha.1](https://github.com/rust-lang/mdBook/compare/v0.4.52...v0.5.0-alpha.1)
107+
108+
### Added
109+
110+
- The location of the generated HTML book is now displayed on the console.
111+
[#2729](https://github.com/rust-lang/mdBook/pull/2729)
112+
- ❗ Added the `optional` field for preprocessors. The default is `false`, so this also changes it so that it is an error if the preprocessor is missing.
113+
[#2797](https://github.com/rust-lang/mdBook/pull/2797)
114+
- ❗ Added `MarkdownOptions` struct to specify settings for markdown rendering.
115+
[#2809](https://github.cocm/rust-lang/mdBook/pull/2809)
116+
- Added sidebar heading navigation. This includes the `output.html.sidebar-header-nav` option to disable it.
117+
[#2822](https://github.com/rust-lang/mdBook/pull/2822)
118+
- Added the mdbook version to the guide.
119+
[#2826](https://github.com/rust-lang/mdBook/pull/2826)
120+
- Added `Book::chapters` and `Book::for_each_chapter_mut` to more conveniently iterate over chapters (instead of all items).
121+
[#2838](https://github.com/rust-lang/mdBook/pull/2838)
122+
- ❗ Added support for definition lists. These are enabled by default, with the option `output.html.definition-lists` to disable it.
123+
[#2847](https://github.com/rust-lang/mdBook/pull/2847)
124+
- ❗ Added support for admonitions. These are enabled by default, with the option `output.html.admonitions` to disable it.
125+
[#2851](https://github.com/rust-lang/mdBook/pull/2851)
126+
127+
### Changed
128+
129+
- ❗ The `mdbook` crate has been split into multiple crates.
130+
[#2766](https://github.com/rust-lang/mdBook/pull/2766)
131+
- The minimum Rust version has been updated to 1.88.
132+
[#2844](https://github.com/rust-lang/mdBook/pull/2844)
133+
- ❗ `pulldown-cmark` has been upgraded to 0.13.0, bringing a large number of fixes to markdown processing.
134+
[#2401](https://github.com/rust-lang/mdBook/pull/2401)
135+
- ❗ Switched public types to `non_exhaustive` to help allow them to change in a backwards-compatible way.
136+
[#2779](https://github.com/rust-lang/mdBook/pull/2779)
137+
[#2823](https://github.com/rust-lang/mdBook/pull/2823)
138+
- ❗ Unknown fields in config are now an error.
139+
[#2787](https://github.com/rust-lang/mdBook/pull/2787)
140+
[#2801](https://github.com/rust-lang/mdBook/pull/2801)
141+
- ❗ Changed `id_from_content` to be private.
142+
[#2791](https://github.com/rust-lang/mdBook/pull/2791)
143+
- ❗ Changed preprocessor `command` to use paths relative to the book root.
144+
[#2796](https://github.com/rust-lang/mdBook/pull/2796)
145+
- ❗ Replaced the `{{#previous}}` and `{{#next}}` handelbars navigation helpers with objects.
146+
[#2794](https://github.com/rust-lang/mdBook/pull/2794)
147+
- ❗ Use embedded SVG instead of fonts for icons, font-awesome 6.2.
148+
[#1330](https://github.com/rust-lang/mdBook/pull/1330)
149+
- The `book.src` field is no longer serialized if it is the default of "src".
150+
[#2800](https://github.com/rust-lang/mdBook/pull/2800)
151+
- ❗ Changed `MDBook` `with_renderer`/`with_preprocessor` to overwrite the entry if an extension of the same name is already loaded.
152+
[#2802](https://github.com/rust-lang/mdBook/pull/2802)
153+
- ❗ Changed CLI `--dest-dir` to be relative to the current directory, not the book root.
154+
[#2806](https://github.com/rust-lang/mdBook/pull/2806)
155+
- ❗ Changed all internal HTML IDs to have an `mdbook-` prefix. This helps avoid namespace conflicts with header IDs.
156+
[#2808](https://github.com/rust-lang/mdBook/pull/2808)
157+
- ❗ `output.html.smart-punctuation` is now `true` by default.
158+
[#2810](https://github.com/rust-lang/mdBook/pull/2810)
159+
- ❗ Renamed `Book::sections` to `Book::items`.
160+
[#2813](https://github.com/rust-lang/mdBook/pull/2813)
161+
- ❗ `output.html.hash-files` is now `true` by default.
162+
[#2820](https://github.com/rust-lang/mdBook/pull/2820)
163+
- Switched from `log` to `tracing`.
164+
[#2829](https://github.com/rust-lang/mdBook/pull/2829)
165+
- ❗ Rewrote the HTML rendering pipeline.
166+
[#2844](https://github.com/rust-lang/mdBook/pull/2844)
167+
- ❗ Links on the print page now link to elements on the print page instead of linking out to the individual chapters.
168+
[#2844](https://github.com/rust-lang/mdBook/pull/2844)
169+
- ❗ Moved theme copy to the Theme type and reduced visibility.
170+
[#2857](https://github.com/rust-lang/mdBook/pull/2857)
171+
- ❗ Cleaned up some fs-related utilities.
172+
[#2856](https://github.com/rust-lang/mdBook/pull/2856)
173+
- ❗ Moved `get_404_output_file` to `HtmlConfig`.
174+
[#2855](https://github.com/rust-lang/mdBook/pull/2855)
175+
- ❗ Moved `take_lines` functions to `mdbook-driver` and made private.
176+
[#2854](https://github.com/rust-lang/mdBook/pull/2854)
177+
- Updated dependencies.
178+
[#2793](https://github.com/rust-lang/mdBook/pull/2793)
179+
[#2869](https://github.com/rust-lang/mdBook/pull/2869)
180+
181+
### Removed
182+
183+
- ❗ Removed `toml` as a public dependency.
184+
[#2773](https://github.com/rust-lang/mdBook/pull/2773)
185+
- ❗ Removed the `book.multilingual` field. This was never used.
186+
[#2775](https://github.com/rust-lang/mdBook/pull/2775)
187+
- ❗ Removed support for google-analytics.
188+
[#2776](https://github.com/rust-lang/mdBook/pull/2776)
189+
- ❗ Removed the very old legacy config support.
190+
[#2783](https://github.com/rust-lang/mdBook/pull/2783)
191+
- ❗ Removed `curly-quotes`, use `output.html.smart-punctuation` instead.
192+
[#2788](https://github.com/rust-lang/mdBook/pull/2788)
193+
- Removed old warning about `book.json`.
194+
[#2789](https://github.com/rust-lang/mdBook/pull/2789)
195+
- ❗ Removed `output.html.copy-fonts`. The default fonts are now always copied unless you override the `theme/fonts/fonts.css` file.
196+
[#2790](https://github.com/rust-lang/mdBook/pull/2790)
197+
- ❗ Removed legacy relative renderer command paths. Relative renderer command paths now must always be relative to the book root.
198+
[#2792](https://github.com/rust-lang/mdBook/pull/2792)
199+
- ❗ Removed the `{{theme_option}}` handlebars helper. It has not been used for a while.
200+
[#2795](https://github.com/rust-lang/mdBook/pull/2795)
201+
- ❗ Removed the `--dest-dir` option to `mdbook test`.
202+
[#2805](https://github.com/rust-lang/mdBook/pull/2805)
203+
204+
### Fixed
205+
206+
- Fixed handling of multiple footnotes in a row.
207+
[#2807](https://github.com/rust-lang/mdBook/pull/2807)
208+
- Fixed ID collisions when the numeric suffix gets used.
209+
[#2846](https://github.com/rust-lang/mdBook/pull/2846)
210+
- Fixed missing css vars for no-js dark mode.
211+
[#2850](https://github.com/rust-lang/mdBook/pull/2850)
212+
3213
## mdBook 0.4.52
4214
[v0.4.51...v0.4.52](https://github.com/rust-lang/mdBook/compare/v0.4.51...v0.4.52)
5215

0 commit comments

Comments
 (0)