[link-forever] fix: images in links · tonywu.org/mdbookkit@872143f

+3

.prettierignore

··· 1 1 **/*.snap 2 2 **/*.snap.new 3 + 4 + docs/app/dist.css 5 + docs/src/app/**/*

+5 -1

README.md

··· 1 + ![mdbookkit hero image](docs/src/media/banner.webp) 2 + 1 3 # mdbookkit 2 4 3 - ![mdbookkit hero image](docs/src/media/banner.webp) 5 + [![crates.io](https://img.shields.io/crates/v/mdbookkit?style=flat-square)](https://crates.io/crates/mdbookkit) 6 + [![documentation](https://img.shields.io/docsrs/mdbookkit?style=flat-square&label=docs.rs)](https://docs.rs/mdbookkit) 7 + [![MIT/Apache-2.0 licensed](https://img.shields.io/crates/l/mdbookkit?style=flat-square)](/LICENSE-APACHE.md) 4 8 5 9 ## [Read the book](https://tonywu6.github.io/mdbookkit)

+3 -7

crates/mdbookkit/README.md

··· 4 4 5 5 Quality-of-life plugins for your [mdBook] project. 6 6 7 - Right now, there are two mdBook [preprocessors], both for generating **correct and 8 - versioned** external links from **easy-to-write** markup. 9 - 10 7 - [**`mdbook-rustdoc-link`**](https://tonywu6.github.io/mdbookkit/rustdoc-link) 11 8 12 9 _rustdoc_-style linking for Rust APIs: write types and function names, get links to ··· 16 13 17 14 _Permalinks_ for your source tree: write relative paths, get links to GitHub. 18 15 19 - > [!TIP] 20 - > 21 - > Preprocessors are standalone programs that mdBook invokes to transform your Markdown 22 - > sources before rendering them. 16 + [![crates.io](https://img.shields.io/crates/v/mdbookkit?style=flat-square)](https://crates.io/crates/mdbookkit) 17 + [![documentation](https://img.shields.io/docsrs/mdbookkit?style=flat-square&label=docs.rs)](https://docs.rs/mdbookkit) 18 + [![MIT/Apache-2.0 licensed](https://img.shields.io/crates/l/mdbookkit?style=flat-square)](/LICENSE-APACHE.md) 23 19 24 20 ## Installation 25 21

+17 -6

crates/mdbookkit/src/bin/link_forever/diagnostic.rs

··· 10 10 11 11 use crate::diagnostics::{Diagnostics, Issue, Problem, ReportBuilder}; 12 12 13 - use super::{Environment, LinkStatus, Pages, RelativeLink}; 13 + use super::{Environment, LinkSpan, LinkStatus, LinkText, Pages, RelativeLink}; 14 14 15 15 impl Environment { 16 16 pub fn report<'a>(&'a self, content: &'a Pages<'a>) -> Reporter<'a> { ··· 19 19 20 20 let root = &self.vcs_root; 21 21 22 - for (base, link) in content 23 - .pages 24 - .iter() 25 - .flat_map(|(base, page)| page.rel_links.iter().map(move |link| (base, link))) 26 - { 22 + let iter = content.pages.iter().flat_map(|(base, page)| { 23 + page.links 24 + .iter() 25 + .flat_map(move |links| links.links().map(move |link| (base, link))) 26 + }); 27 + 28 + for (base, link) in iter { 27 29 let diagnostic = LinkDiagnostic { link, base, root }; 28 30 sorted 29 31 .entry(base) ··· 181 183 } 182 184 } 183 185 } 186 + 187 + impl<'a> LinkSpan<'a> { 188 + fn links(&self) -> impl Iterator<Item = &'_ RelativeLink<'a>> { 189 + self.0.iter().filter_map(|item| match item { 190 + LinkText::Link(link) => Some(link), 191 + LinkText::Text(..) => None, 192 + }) 193 + } 194 + }

+162 -66

crates/mdbookkit/src/bin/link_forever/mod.rs

··· 18 18 19 19 use crate::{ 20 20 env::ErrorHandling, 21 - log_debug, 21 + log_debug, log_warning, 22 22 markdown::{PatchStream, Spanned}, 23 23 }; 24 24 ··· 45 45 46 46 let fragments = content.take_fragments(); 47 47 48 - for (base, link) in content 49 - .pages 50 - .iter_mut() 51 - .flat_map(|(base, page)| page.rel_links.iter_mut().map(move |link| (base, link))) 52 - { 48 + let iter = content.pages.iter_mut().flat_map(|(base, page)| { 49 + page.links 50 + .iter_mut() 51 + .flat_map(move |links| links.links_mut().map(move |link| (base, link))) 52 + }); 53 + 54 + for (base, link) in iter { 53 55 let file = if link.link.starts_with('/') { 54 56 self.vcs_root.join(&link.link[1..]) 55 57 } else { ··· 316 318 317 319 struct Page<'a> { 318 320 source: &'a str, 319 - rel_links: Vec<RelativeLink<'a>>, 321 + links: Vec<LinkSpan<'a>>, 320 322 fragments: HashSet<String>, 321 323 } 322 324 325 + struct LinkSpan<'a>(Vec<LinkText<'a>>); 326 + 327 + enum LinkText<'a> { 328 + Text(Event<'a>), 329 + Link(RelativeLink<'a>), 330 + } 331 + 323 332 struct RelativeLink<'a> { 333 + status: LinkStatus, 324 334 span: Range<usize>, 325 335 link: CowStr<'a>, 326 336 usage: LinkUsage, 327 337 title: CowStr<'a>, 328 - inner: Vec<Event<'a>>, 329 - status: LinkStatus, 338 + } 339 + 340 + #[derive(Clone, Copy, PartialEq)] 341 + enum LinkUsage { 342 + Link, 343 + Image, 330 344 } 331 345 332 346 #[derive(Debug, Default, Clone)] ··· 348 362 NoSuchFragment, 349 363 /// Link to a file under source control but link generation failed 350 364 Error(String), 351 - } 352 - 353 - #[derive(Clone, Copy, PartialEq)] 354 - enum LinkUsage { 355 - Link, 356 - Image, 357 365 } 358 366 359 367 impl<'a> Pages<'a> { ··· 398 406 { 399 407 let mut this = Self { 400 408 source, 401 - rel_links: Default::default(), 409 + links: Default::default(), 402 410 fragments: Default::default(), 403 411 }; 404 412 ··· 410 418 let mut heading: Option<Heading<'_>> = None; 411 419 let mut counter: HashMap<String, usize> = Default::default(); 412 420 413 - let mut link: Option<RelativeLink<'_>> = None; 421 + let mut opened: Option<LinkSpan<'_>> = None; 414 422 415 423 for (event, span) in stream { 416 424 match event { ··· 435 443 } 436 444 437 445 Event::Start(tag @ (Tag::Link { .. } | Tag::Image { .. })) => { 438 - let (usage, dest_url, title) = match tag { 446 + let (usage, link, title) = match tag { 439 447 Tag::Link { 440 448 dest_url, title, .. 441 449 } => (LinkUsage::Link, dest_url, title), ··· 444 452 } => (LinkUsage::Image, dest_url, title), 445 453 _ => unreachable!(), 446 454 }; 447 - if link.is_some() { 448 - bail!("unexpected {usage:?} in {usage:?} at {span:?}") 449 - } 450 - link = Some(RelativeLink { 455 + let link = RelativeLink { 456 + status: LinkStatus::External, 451 457 span, 452 - link: dest_url, 458 + link, 453 459 usage, 454 460 title, 455 - inner: vec![], 456 - status: LinkStatus::External, 457 - }); 461 + } 462 + .pipe(LinkText::Link); 463 + match opened.as_mut() { 464 + Some(opened) => opened.0.push(link), 465 + None => opened = Some(LinkSpan(vec![link])), 466 + } 458 467 } 459 468 460 - Event::End(end @ (TagEnd::Link | TagEnd::Image)) => { 469 + event @ Event::End(end @ (TagEnd::Link | TagEnd::Image)) => { 461 470 let usage = match end { 462 471 TagEnd::Link => LinkUsage::Link, 463 472 TagEnd::Image => LinkUsage::Image, 464 473 _ => unreachable!(), 465 474 }; 466 - let Some(link) = link.take() else { 475 + let Some(mut items) = opened.take() else { 467 476 bail!("unexpected {usage:?} at {span:?}") 468 477 }; 469 - if link.span != span { 470 - bail!("mismatching span, expected {:?}, got {span:?}", link.span); 478 + items.0.push(LinkText::Text(event)); 479 + if &span == items.span() { 480 + this.links.push(items); 481 + } else { 482 + opened = Some(items) 471 483 } 472 - if link.usage != usage { 473 - bail!("unexpected {usage:?}, expected {:?}", link.usage) 474 - } 475 - this.rel_links.push(link); 476 484 } 477 485 478 - event => match (heading.as_mut(), link.as_mut()) { 486 + event => match (heading.as_mut(), opened.as_mut()) { 479 487 (Some(heading), Some(link)) => { 480 488 heading.text.push(event.clone()); 481 - link.inner.push(event); 489 + link.0.push(LinkText::Text(event)); 482 490 } 483 491 (Some(heading), None) => { 484 492 heading.text.push(event); 485 493 } 486 494 (None, Some(link)) => { 487 - link.inner.push(event); 495 + link.0.push(LinkText::Text(event)); 488 496 } 489 497 (None, None) => {} 490 498 }, ··· 495 503 } 496 504 497 505 fn emit(&self) -> Result<String> { 498 - self.rel_links 506 + self.links 499 507 .iter() 500 - .filter_map(|link| { 501 - if !matches!(link.status, LinkStatus::Permalink | LinkStatus::Rewritten) { 502 - return None; 503 - } 504 - let start = match link.usage { 505 - LinkUsage::Link => Tag::Link { 506 - link_type: LinkType::Inline, 507 - dest_url: link.link.clone(), 508 - title: link.title.clone(), 509 - id: CowStr::Borrowed(""), 510 - }, 511 - LinkUsage::Image => Tag::Image { 512 - link_type: LinkType::Inline, 513 - dest_url: link.link.clone(), 514 - title: link.title.clone(), 515 - id: CowStr::Borrowed(""), 516 - }, 517 - }; 518 - let end = match link.usage { 519 - LinkUsage::Link => TagEnd::Link, 520 - LinkUsage::Image => TagEnd::Image, 521 - }; 522 - std::iter::once(Event::Start(start)) 523 - .chain(link.inner.iter().cloned()) 524 - .chain(std::iter::once(Event::End(end))) 525 - .pipe(|events| Some((events, link.span.clone()))) 526 - }) 508 + .filter_map(EmitLinkSpan::new) 527 509 .pipe(|stream| PatchStream::new(self.source, stream)) 528 - .into_string()? 510 + .into_string() 511 + .tap_err(log_warning!())? 529 512 .pipe(Ok) 530 513 } 531 514 ··· 553 536 fn insert_id(&mut self, id: &str, counter: &mut HashMap<String, usize>) { 554 537 counter.insert(id.into(), 1); 555 538 self.fragments.insert(id.into()); 539 + } 540 + } 541 + 542 + impl<'a> LinkSpan<'a> { 543 + fn links_mut(&mut self) -> impl Iterator<Item = &'_ mut RelativeLink<'a>> { 544 + self.0.iter_mut().filter_map(|item| match item { 545 + LinkText::Link(link) => Some(link), 546 + LinkText::Text(..) => None, 547 + }) 548 + } 549 + 550 + fn span(&self) -> &Range<usize> { 551 + match &self.0[0] { 552 + LinkText::Link(link) => &link.span, 553 + LinkText::Text(..) => unreachable!("first item in LinkSpan must be a Link"), 554 + } 555 + } 556 + } 557 + 558 + struct EmitLinkSpan<'a> { 559 + iter: std::slice::Iter<'a, LinkText<'a>>, 560 + opened: Vec<LinkUsage>, 561 + } 562 + 563 + impl<'a> Iterator for EmitLinkSpan<'a> { 564 + type Item = Event<'a>; 565 + 566 + fn next(&mut self) -> Option<Self::Item> { 567 + for next in self.iter.by_ref() { 568 + match next { 569 + LinkText::Text(text) => { 570 + match (text, self.opened.last()) { 571 + (Event::End(TagEnd::Link), Some(LinkUsage::Link)) => { 572 + self.opened.pop(); 573 + return Some(text.clone()); 574 + } 575 + (Event::End(TagEnd::Image), Some(LinkUsage::Image)) => { 576 + self.opened.pop(); 577 + return Some(text.clone()); 578 + } 579 + (Event::End(TagEnd::Link | TagEnd::Image), None) => { 580 + // skip this end tag because the link was skipped 581 + continue; 582 + } 583 + _ => { 584 + return Some(text.clone()); 585 + } 586 + }; 587 + } 588 + LinkText::Link(link) => { 589 + match (link.will_emit(), self.opened.is_empty()) { 590 + (Some(usage), _) => { 591 + self.opened.push(usage); 592 + return Some(Event::Start(link.emit())); 593 + } 594 + (None, false) => { 595 + return Some(Event::Start(link.emit())); 596 + } 597 + (None, true) => { 598 + continue; 599 + } 600 + }; 601 + } 602 + }; 603 + } 604 + None 605 + } 606 + } 607 + 608 + impl<'a> EmitLinkSpan<'a> { 609 + fn new(links: &'a LinkSpan<'a>) -> Option<(Self, Range<usize>)> { 610 + let span = links.0.iter().find_map(|link| match &link { 611 + LinkText::Link(link) => { 612 + if link.will_emit().is_some() { 613 + Some(link.span.clone()) 614 + } else { 615 + None 616 + } 617 + } 618 + _ => None, 619 + })?; 620 + let iter = EmitLinkSpan { 621 + iter: links.0.iter(), 622 + opened: vec![], 623 + }; 624 + Some((iter, span)) 625 + } 626 + } 627 + 628 + impl RelativeLink<'_> { 629 + fn emit(&self) -> Tag<'_> { 630 + match self.usage { 631 + LinkUsage::Link => Tag::Link { 632 + link_type: LinkType::Inline, 633 + dest_url: self.link.clone(), 634 + title: self.title.clone(), 635 + id: CowStr::Borrowed(""), 636 + }, 637 + LinkUsage::Image => Tag::Image { 638 + link_type: LinkType::Inline, 639 + dest_url: self.link.clone(), 640 + title: self.title.clone(), 641 + id: CowStr::Borrowed(""), 642 + }, 643 + } 644 + } 645 + 646 + fn will_emit(&self) -> Option<LinkUsage> { 647 + if matches!(self.status, LinkStatus::Permalink | LinkStatus::Rewritten) { 648 + Some(self.usage) 649 + } else { 650 + None 651 + } 556 652 } 557 653 } 558 654

+16 -5

crates/mdbookkit/src/markdown.rs

··· 44 44 return Some(Ok(Cow::Borrowed(&self.source[start..]))); 45 45 }; 46 46 47 + if start > span.start { 48 + panic!("span {span:?} is backwards from already yielded span ending at {start}") 49 + } 50 + 47 51 let patch = match String::new().pipe(|mut out| cmark(events, &mut out).and(Ok(out))) { 48 52 Err(error) => return Some(Err(error)), 49 53 Ok(patch) => patch, ··· 59 63 impl<'a, S> PatchStream<'a, S> { 60 64 /// Create a new patch stream. 61 65 /// 62 - /// `stream` should be an [`Iterator`] yielding (`E`, [`Range<usize>`]), where `E` is an 63 - /// [`Iterator`] yielding [`Event`]s. 66 + /// `stream` should be an [`Iterator`] yielding tuples of (`events`, `range`): 67 + /// 68 + /// - `events` is an [`Iterator`] yielding [`Event`]s which is the replacement 69 + /// Markdown to be rendered into `source` using [`pulldown_cmark_to_cmark`]. 70 + /// 71 + /// - `range` is a [`Range<usize>`] representing the byte span in `source` that 72 + /// should be patched. 64 73 /// 65 - /// [`Range<usize>`] is the byte span in `source` that should be patched. 74 + /// **The yielded ranges must not overlap or decrease**, that is, for `span1` and 75 + /// `span2`, where `span1` is yielded before `span2`, `span1.end <= span2.start`. 66 76 /// 67 - /// `E` is the replacement event stream to be rendered into `source` 68 - /// using [`pulldown_cmark_to_cmark`]. 77 + /// ## Panics 78 + /// 79 + /// Panic if ranges in `stream` are not monotonically increasing. 69 80 pub fn new(source: &'a str, stream: S) -> Self { 70 81 Self { 71 82 source,

+20 -12

crates/mdbookkit/tests/link_forever.rs

··· 2 2 use log::LevelFilter; 3 3 use tap::Pipe; 4 4 5 + use url::Url; 6 + 5 7 use mdbookkit::{ 6 8 bin::link_forever::{Config, Environment, GitHubPermalink, Pages}, 9 + logging::ConsoleLogger, 7 10 markdown::mdbook_markdown, 8 11 }; 9 - use url::Url; 10 12 use util_testing::{portable_snapshots, test_document, CARGO_WORKSPACE_DIR}; 11 13 12 14 #[test] 13 15 fn test_links() -> Result<()> { 16 + ConsoleLogger::install("link-forever"); 17 + 14 18 let env = Environment { 15 - book_src: CARGO_WORKSPACE_DIR.join("crates/mdbookkit/tests/")?, 19 + book_src: CARGO_WORKSPACE_DIR.join("crates/mdbookkit/")?, 16 20 vcs_root: CARGO_WORKSPACE_DIR.clone(), 17 21 fmt_link: GitHubPermalink::new("lorem", "ipsum", "dolor").pipe(Box::new), 18 22 markdown: mdbook_markdown(), ··· 24 28 25 29 let mut pages = Pages::new(mdbook_markdown()); 26 30 27 - let main_page = test_document!("tests/link-forever.md"); 28 - let side_page = test_document!("tests/ra-known-quirks.md"); 31 + let tests = [ 32 + test_document!("tests/ra-known-quirks.md"), // only for providing anchors 33 + test_document!("tests/link-forever.md"), 34 + test_document!("../README.md"), 35 + ]; 29 36 30 - pages.insert(main_page.file.clone(), main_page.source)?; 31 - pages.insert(side_page.file.clone(), side_page.source)?; 37 + for page in tests.iter() { 38 + pages.insert(page.file.clone(), page.source)?; 39 + } 32 40 33 41 env.resolve(&mut pages); 34 42 35 - let name = main_page.name.clone(); 36 - 37 - let output = pages.emit(&main_page.file)?; 43 + for page in tests { 44 + let output = pages.emit(&page.file)?; 45 + let name = page.name; 46 + portable_snapshots!().test(|| insta::assert_snapshot!(format!("{name}"), output))?; 47 + } 38 48 39 49 let report = env 40 50 .report(&pages) ··· 45 55 .build() 46 56 .to_report(); 47 57 48 - portable_snapshots!().test(|| insta::assert_snapshot!(format!("{name}.stderr"), report))?; 49 - 50 - portable_snapshots!().test(|| insta::assert_snapshot!(format!("{name}"), output))?; 58 + portable_snapshots!().test(|| insta::assert_snapshot!("_stderr", report))?; 51 59 52 60 Ok(()) 53 61 }

+49

crates/mdbookkit/tests/snaps/link_forever/README.snap

··· 1 + --- 2 + source: crates/mdbookkit/tests/link_forever.rs 3 + expression: output 4 + --- 5 + # mdbookkit 6 + 7 + ![mdbookkit hero image](https://github.com/lorem/ipsum/tree/dolor/docs/src/media/banner.webp) 8 + 9 + Quality-of-life plugins for your [mdBook] project. 10 + 11 + - [**`mdbook-rustdoc-link`**](https://tonywu6.github.io/mdbookkit/rustdoc-link) 12 + 13 + _rustdoc_-style linking for Rust APIs: write types and function names, get links to 14 + _docs.rs_ 15 + 16 + - [**`mdbook-link-forever`**](https://tonywu6.github.io/mdbookkit/link-forever) 17 + 18 + _Permalinks_ for your source tree: write relative paths, get links to GitHub. 19 + 20 + [![crates.io](https://img.shields.io/crates/v/mdbookkit?style=flat-square)](https://crates.io/crates/mdbookkit) 21 + [![documentation](https://img.shields.io/docsrs/mdbookkit?style=flat-square&label=docs.rs)](https://docs.rs/mdbookkit) 22 + [![MIT/Apache-2.0 licensed](https://img.shields.io/crates/l/mdbookkit?style=flat-square)](https://github.com/lorem/ipsum/tree/dolor/LICENSE-APACHE.md) 23 + 24 + ## Installation 25 + 26 + If you are interested in any of these plugins, visit their respective pages for usage 27 + instructions, linked above. 28 + 29 + If you want to install all of them: 30 + 31 + ```bash 32 + cargo install mdbookkit --all-features 33 + ``` 34 + 35 + Precompiled binaries are also available from [GitHub releases][gh-releases]. 36 + 37 + ## License 38 + 39 + This project is released under the [Apache 2.0 License](https://github.com/lorem/ipsum/tree/dolor/LICENSE-APACHE.md) and the 40 + [MIT License](https://github.com/lorem/ipsum/tree/dolor/LICENSE-MIT.md). 41 + 42 +  43 + 44 + [mdBook]: https://rust-lang.github.io/mdBook/ 45 + [`mdbookkit`]: https://crates.io/crates/mdbookkit 46 + [preprocessors]: https://rust-lang.github.io/mdBook/format/configuration/preprocessors.html 47 + [gh-releases]: https://github.com/tonywu6/mdbookkit/releases 48 + 49 +

+215

crates/mdbookkit/tests/snaps/link_forever/_stderr.snap

··· 1 + --- 2 + source: crates/mdbookkit/tests/link_forever.rs 3 + expression: report 4 + --- 5 + info: url ignored 6 + ╭─[crates/mdbookkit/tests/tests/link-forever.md:45:13] 7 + 44 │ 8 + 45 │ ## heading: <https://räksmörgås.josefsson.org/> 9 + · ─────────────────────────────────── 10 + 46 │ 11 + 47 │ # canonical urls 12 + 48 │ 13 + 49 │ found: <https://example.org/book/tests/ra-known-quirks> 14 + 50 │ 15 + 51 │ found: <https://example.org/book/tests/ra-known-quirks.html> 16 + 52 │ 17 + 53 │ missing: <https://example.org/book/404> 18 + 54 │ 19 + 55 │ ignored: <https://example.com/book/ra-known-quirks> 20 + · ────────────────────────────────────────── 21 + 56 │ 22 + 57 │ # image-in-link 23 + 58 │ 24 + 59 │ [![crates.io](https://img.shields.io/crates/v/mdbookkit?style=flat-square)](https://crates.io/crates/mdbookkit) 25 + · ──────────────────────────────────────────────────────────────────────────────────────────────────────────────── 26 + 60 │ 27 + 61 │ [![selfie](/crates/mdbookkit/tests/tests/Macaca_nigra_self-portrait_large.jpg)](https://commons.wikimedia.org/wiki/File:Macaca_nigra_self-portrait_large.jpg) 28 + · ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── 29 + 62 │ 30 + ╰──── 31 + 32 + info: file under src/ 33 + ╭─[crates/mdbookkit/tests/tests/link-forever.md:15:1] 34 + 14 │ 35 + 15 │ [Known quirks](./ra-known-quirks.md) 36 + · ──────────────────────────────────── 37 + 16 │ 38 + 17 │ [link_forever.rs](../link_forever.rs) 39 + · ───────────────────────────────────── 40 + 18 │ 41 + 19 │ ![selfie](Macaca_nigra_self-portrait_large.jpg) 42 + · ─────────────────────────────────────────────── 43 + 20 │ 44 + 21 │ # fragments 45 + 22 │ 46 + 23 │ [Fragments](./link-forever.md#fragments) 47 + · ──────────────────────────────────────── 48 + 24 │ 49 + 25 │ [Heading 1](./link-forever.md#heading-sqrt3x-11x2) 50 + · ────────────────────────────────────────────────── 51 + 26 │ 52 + 27 │ [Heading 2](./link-forever.md#heading-httpsräksmörgåsjosefssonorg) 53 + · ────────────────────────────────────────────────────────────────── 54 + 28 │ 55 + 29 │ [macro_export](./ra-known-quirks.md#macro_export) 56 + · ───────────────────────────────────────────────── 57 + 30 │ 58 + ╰──── 59 + 60 + info: path converted to relative path 61 + ╭─[crates/mdbookkit/tests/tests/link-forever.md:11:1] 62 + 10 │ 63 + 11 │ [link-forever.md](/crates/mdbookkit/tests/tests/link-forever.md#absolute-paths) 64 + · ───────────────────────────────────────┬─────────────────────────────────────── 65 + · ╰── crates/mdbookkit/tests/tests/link-forever.md 66 + 12 │ 67 + ╰──── 68 + ╭─[crates/mdbookkit/tests/tests/link-forever.md:61:2] 69 + 60 │ 70 + 61 │ [![selfie](/crates/mdbookkit/tests/tests/Macaca_nigra_self-portrait_large.jpg)](https://commons.wikimedia.org/wiki/File:Macaca_nigra_self-portrait_large.jpg) 71 + · ──────────────────────────────────────┬────────────────────────────────────── 72 + · ╰── crates/mdbookkit/tests/tests/Macaca_nigra_self-portrait_large.jpg 73 + 62 │ 74 + 63 │ [![selfie](/crates/mdbookkit/tests/tests/Macaca_nigra_self-portrait_large.jpg) <br> Self-portrait of a female Macaca nigra in North Sulawesi (2011)](/crates/mdbookkit/tests/tests/Macaca_nigra_self-portrait_large.jpg) 75 + · ────────────────────────────────────────────────────────────────────────────────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────┬ 76 + · │ ╰── crates/mdbookkit/tests/tests/Macaca_nigra_self-portrait_large.jpg 77 + · ╰── crates/mdbookkit/tests/tests/Macaca_nigra_self-portrait_large.jpg 78 + ╰──── 79 + 80 + info: path converted to permalink 81 + ╭─[crates/mdbookkit/tests/tests/link-forever.md:3:1] 82 + 2 │ 83 + 3 │ [Cargo.toml](../../../../Cargo.toml) 84 + · ──────────────────┬───────────────── 85 + · ╰── https://github.com/lorem/ipsum/tree/dolor/Cargo.toml 86 + 4 │ 87 + 5 │ ![error reporting](../../../../docs/src/rustdoc-link/media/error-reporting.png) 88 + · ───────────────────────────────────────┬─────────────────────────────────────── 89 + · ╰── https://github.com/lorem/ipsum/tree/dolor/docs/src/rustdoc-link/media/error-reporting.png 90 + 6 │ 91 + 7 │ # absolute paths 92 + 8 │ 93 + 9 │ [LICENSE-APACHE.md](/LICENSE-APACHE.md) 94 + · ───────────────────┬─────────────────── 95 + · ╰── https://github.com/lorem/ipsum/tree/dolor/LICENSE-APACHE.md 96 + 10 │ 97 + ╰──── 98 + 99 + warning: file not found 100 + ╭─[crates/mdbookkit/tests/tests/link-forever.md:33:1] 101 + 32 │ 102 + 33 │ [Cargo.lock](../../Cargo.lock) 103 + · ───────────────┬────────────── 104 + · ╰── file does not exist at path: crates/mdbookkit/Cargo.lock 105 + 34 │ 106 + 35 │ [`//LICENSE-MIT.md`](//LICENSE-MIT.md) 107 + · ───────────────────┬────────────────── 108 + · ╰── file does not exist at path: //LICENSE-MIT.md 109 + 36 │ 110 + 37 │ ![shinjuku.jpg](shinjuku.jpg) 111 + · ──────────────┬────────────── 112 + · ╰── file does not exist at path: crates/mdbookkit/tests/tests/shinjuku.jpg 113 + 38 │ 114 + 39 │ # fragment not found 115 + 40 │ 116 + 41 │ [associated items](../tests/ra-known-quirks.md#associated_items_on_primitive_types) 117 + 42 │ 118 + 43 │ ## heading: $\sqrt{3x-1}+(1+x)^2$ 119 + 44 │ 120 + 45 │ ## heading: <https://räksmörgås.josefsson.org/> 121 + 46 │ 122 + 47 │ # canonical urls 123 + 48 │ 124 + 49 │ found: <https://example.org/book/tests/ra-known-quirks> 125 + · ────────────────────────┬─────────────────────── 126 + · ╰── file does not exist at path: crates/mdbookkit/tests/ra-known-quirks.md 127 + 50 │ 128 + 51 │ found: <https://example.org/book/tests/ra-known-quirks.html> 129 + · ──────────────────────────┬────────────────────────── 130 + · ╰── file does not exist at path: crates/mdbookkit/tests/ra-known-quirks.md 131 + 52 │ 132 + 53 │ missing: <https://example.org/book/404> 133 + · ───────────────┬────────────── 134 + · ╰── file does not exist at path: crates/mdbookkit/404.md 135 + 54 │ 136 + ╰──── 137 + 138 + warning: no such fragment 139 + ╭─[crates/mdbookkit/tests/tests/link-forever.md:41:1] 140 + 40 │ 141 + 41 │ [associated items](../tests/ra-known-quirks.md#associated_items_on_primitive_types) 142 + · ─────────────────────────────────────────┬───────────────────────────────────────── 143 + · ╰── #associated_items_on_primitive_types not found in crates/mdbookkit/tests/tests/ra-known-quirks.md 144 + 42 │ 145 + ╰──── 146 + 147 + info: url ignored 148 + ╭─[crates/mdbookkit/README.md:5:34] 149 + 4 │ 150 + 5 │ Quality-of-life plugins for your [mdBook] project. 151 + · ──────── 152 + 6 │ 153 + 7 │ - [**`mdbook-rustdoc-link`**](https://tonywu6.github.io/mdbookkit/rustdoc-link) 154 + · ───────────────────────────────────────────────────────────────────────────── 155 + 8 │ 156 + 9 │ _rustdoc_-style linking for Rust APIs: write types and function names, get links to 157 + 10 │ _docs.rs_ 158 + 11 │ 159 + 12 │ - [**`mdbook-link-forever`**](https://tonywu6.github.io/mdbookkit/link-forever) 160 + · ───────────────────────────────────────────────────────────────────────────── 161 + 13 │ 162 + 14 │ _Permalinks_ for your source tree: write relative paths, get links to GitHub. 163 + 15 │ 164 + 16 │ [![crates.io](https://img.shields.io/crates/v/mdbookkit?style=flat-square)](https://crates.io/crates/mdbookkit) 165 + · ──────────────────────────────────────────────────────────────────────────────────────────────────────────────── 166 + 17 │ [![documentation](https://img.shields.io/docsrs/mdbookkit?style=flat-square&label=docs.rs)](https://docs.rs/mdbookkit) 167 + · ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── 168 + 18 │ [![MIT/Apache-2.0 licensed](https://img.shields.io/crates/l/mdbookkit?style=flat-square)](/LICENSE-APACHE.md) 169 + · ─────────────────────────────────────────────────────────────────────────────────────── 170 + 19 │ 171 + ╰──── 172 + ╭─[crates/mdbookkit/README.md:31:46] 173 + 30 │ 174 + 31 │ Precompiled binaries are also available from [GitHub releases][gh-releases]. 175 + · ────────────────────────────── 176 + 32 │ 177 + ╰──── 178 + 179 + info: path converted to permalink 180 + ╭─[crates/mdbookkit/README.md:3:1] 181 + 2 │ 182 + 3 │ ![mdbookkit hero image](/docs/src/media/banner.webp) 183 + · ──────────────────────────┬───────────────────────── 184 + · ╰── https://github.com/lorem/ipsum/tree/dolor/docs/src/media/banner.webp 185 + 4 │ 186 + ╰──── 187 + ╭─[crates/mdbookkit/README.md:18:1] 188 + 17 │ [![documentation](https://img.shields.io/docsrs/mdbookkit?style=flat-square&label=docs.rs)](https://docs.rs/mdbookkit) 189 + 18 │ [![MIT/Apache-2.0 licensed](https://img.shields.io/crates/l/mdbookkit?style=flat-square)](/LICENSE-APACHE.md) 190 + · ──────────────────────────────────────────────────────┬────────────────────────────────────────────────────── 191 + · ╰── https://github.com/lorem/ipsum/tree/dolor/LICENSE-APACHE.md 192 + 19 │ 193 + 20 │ ## Installation 194 + 21 │ 195 + 22 │ If you are interested in any of these plugins, visit their respective pages for usage 196 + 23 │ instructions, linked above. 197 + 24 │ 198 + 25 │ If you want to install all of them: 199 + 26 │ 200 + 27 │ ```bash 201 + 28 │ cargo install mdbookkit --all-features 202 + 29 │ ``` 203 + 30 │ 204 + 31 │ Precompiled binaries are also available from [GitHub releases][gh-releases]. 205 + 32 │ 206 + 33 │ ## License 207 + 34 │ 208 + 35 │ This project is released under the [Apache 2.0 License](/LICENSE-APACHE.md) and the 209 + · ────────────────────┬─────────────────── 210 + · ╰── https://github.com/lorem/ipsum/tree/dolor/LICENSE-APACHE.md 211 + 36 │ [MIT License](/LICENSE-MIT.md). 212 + · ───────────────┬────────────── 213 + · ╰── https://github.com/lorem/ipsum/tree/dolor/LICENSE-MIT.md 214 + 37 │ 215 + ╰────

+9 -5

crates/mdbookkit/tests/snaps/link_forever/link-forever.snap

··· 4 4 --- 5 5 # relative paths 6 6 7 - [Cargo.toml](https://github.com/lorem/ipsum/tree/dolor/crates/mdbookkit/Cargo.toml) 8 - 9 - [src/lib.rs](https://github.com/lorem/ipsum/tree/dolor/crates/mdbookkit/src/lib.rs) 7 + [Cargo.toml](https://github.com/lorem/ipsum/tree/dolor/Cargo.toml) 10 8 11 9 ![error reporting](https://github.com/lorem/ipsum/tree/dolor/docs/src/rustdoc-link/media/error-reporting.png) 12 10 ··· 23 21 [link_forever.rs](../link_forever.rs) 24 22 25 23 ![selfie](Macaca_nigra_self-portrait_large.jpg) 26 - 27 - <https://commons.wikimedia.org/wiki/File:Macaca_nigra_self-portrait_large.jpg> 28 24 29 25 # fragments 30 26 ··· 61 57 missing: <https://example.org/book/404> 62 58 63 59 ignored: <https://example.com/book/ra-known-quirks> 60 + 61 + # image-in-link 62 + 63 + [![crates.io](https://img.shields.io/crates/v/mdbookkit?style=flat-square)](https://crates.io/crates/mdbookkit) 64 + 65 + [![selfie](Macaca_nigra_self-portrait_large.jpg)](https://commons.wikimedia.org/wiki/File:Macaca_nigra_self-portrait_large.jpg) 66 + 67 + [![selfie](Macaca_nigra_self-portrait_large.jpg) <br> Self-portrait of a female Macaca nigra in North Sulawesi (2011)](Macaca_nigra_self-portrait_large.jpg)

-142

crates/mdbookkit/tests/snaps/link_forever/link-forever.stderr.snap

··· 1 - --- 2 - source: crates/mdbookkit/tests/link_forever.rs 3 - expression: report 4 - --- 5 - info: url ignored 6 - ╭─[crates/mdbookkit/tests/tests/link-forever.md:23:1] 7 - 22 │ 8 - 23 │ <https://commons.wikimedia.org/wiki/File:Macaca_nigra_self-portrait_large.jpg> 9 - · ────────────────────────────────────────────────────────────────────────────── 10 - 24 │ 11 - ╰──── 12 - ╭─[crates/mdbookkit/tests/tests/link-forever.md:49:13] 13 - 48 │ 14 - 49 │ ## heading: <https://räksmörgås.josefsson.org/> 15 - · ─────────────────────────────────── 16 - 50 │ 17 - 51 │ # canonical urls 18 - 52 │ 19 - 53 │ found: <https://example.org/book/tests/ra-known-quirks> 20 - 54 │ 21 - 55 │ found: <https://example.org/book/tests/ra-known-quirks.html> 22 - 56 │ 23 - 57 │ missing: <https://example.org/book/404> 24 - 58 │ 25 - 59 │ ignored: <https://example.com/book/ra-known-quirks> 26 - · ────────────────────────────────────────── 27 - ╰──── 28 - 29 - info: file under src/ 30 - ╭─[crates/mdbookkit/tests/tests/link-forever.md:17:1] 31 - 16 │ 32 - 17 │ [Known quirks](./ra-known-quirks.md) 33 - · ──────────────────────────────────── 34 - 18 │ 35 - 19 │ [link_forever.rs](../link_forever.rs) 36 - · ───────────────────────────────────── 37 - 20 │ 38 - 21 │ ![selfie](Macaca_nigra_self-portrait_large.jpg) 39 - · ─────────────────────────────────────────────── 40 - 22 │ 41 - 23 │ <https://commons.wikimedia.org/wiki/File:Macaca_nigra_self-portrait_large.jpg> 42 - 24 │ 43 - 25 │ # fragments 44 - 26 │ 45 - 27 │ [Fragments](./link-forever.md#fragments) 46 - · ──────────────────────────────────────── 47 - 28 │ 48 - 29 │ [Heading 1](./link-forever.md#heading-sqrt3x-11x2) 49 - · ────────────────────────────────────────────────── 50 - 30 │ 51 - 31 │ [Heading 2](./link-forever.md#heading-httpsräksmörgåsjosefssonorg) 52 - · ────────────────────────────────────────────────────────────────── 53 - 32 │ 54 - 33 │ [macro_export](./ra-known-quirks.md#macro_export) 55 - · ───────────────────────────────────────────────── 56 - 34 │ 57 - ╰──── 58 - ╭─[crates/mdbookkit/tests/tests/link-forever.md:53:8] 59 - 52 │ 60 - 53 │ found: <https://example.org/book/tests/ra-known-quirks> 61 - · ──────────────────────────────────────────────── 62 - 54 │ 63 - 55 │ found: <https://example.org/book/tests/ra-known-quirks.html> 64 - · ───────────────────────────────────────────────────── 65 - 56 │ 66 - ╰──── 67 - 68 - info: path converted to relative path 69 - ╭─[crates/mdbookkit/tests/tests/link-forever.md:13:1] 70 - 12 │ 71 - 13 │ [link-forever.md](/crates/mdbookkit/tests/tests/link-forever.md#absolute-paths) 72 - · ───────────────────────────────────────┬─────────────────────────────────────── 73 - · ╰── crates/mdbookkit/tests/tests/link-forever.md 74 - 14 │ 75 - ╰──── 76 - 77 - info: path converted to permalink 78 - ╭─[crates/mdbookkit/tests/tests/link-forever.md:3:1] 79 - 2 │ 80 - 3 │ [Cargo.toml](../../Cargo.toml) 81 - · ───────────────┬────────────── 82 - · ╰── https://github.com/lorem/ipsum/tree/dolor/crates/mdbookkit/Cargo.toml 83 - 4 │ 84 - 5 │ [src/lib.rs](../../src/lib.rs) 85 - · ───────────────┬────────────── 86 - · ╰── https://github.com/lorem/ipsum/tree/dolor/crates/mdbookkit/src/lib.rs 87 - 6 │ 88 - 7 │ ![error reporting](../../../../docs/src/rustdoc-link/media/error-reporting.png) 89 - · ───────────────────────────────────────┬─────────────────────────────────────── 90 - · ╰── https://github.com/lorem/ipsum/tree/dolor/docs/src/rustdoc-link/media/error-reporting.png 91 - 8 │ 92 - 9 │ # absolute paths 93 - 10 │ 94 - 11 │ [LICENSE-APACHE.md](/LICENSE-APACHE.md) 95 - · ───────────────────┬─────────────────── 96 - · ╰── https://github.com/lorem/ipsum/tree/dolor/LICENSE-APACHE.md 97 - 12 │ 98 - ╰──── 99 - 100 - warning: file not found 101 - ╭─[crates/mdbookkit/tests/tests/link-forever.md:37:1] 102 - 36 │ 103 - 37 │ [Cargo.lock](../../Cargo.lock) 104 - · ───────────────┬────────────── 105 - · ╰── file does not exist at path: crates/mdbookkit/Cargo.lock 106 - 38 │ 107 - 39 │ [`//LICENSE-MIT.md`](//LICENSE-MIT.md) 108 - · ───────────────────┬────────────────── 109 - · ╰── file does not exist at path: //LICENSE-MIT.md 110 - 40 │ 111 - 41 │ ![shinjuku.jpg](shinjuku.jpg) 112 - · ──────────────┬────────────── 113 - · ╰── file does not exist at path: crates/mdbookkit/tests/tests/shinjuku.jpg 114 - 42 │ 115 - 43 │ # fragment not found 116 - 44 │ 117 - 45 │ [associated items](../tests/ra-known-quirks.md#associated_items_on_primitive_types) 118 - 46 │ 119 - 47 │ ## heading: $\sqrt{3x-1}+(1+x)^2$ 120 - 48 │ 121 - 49 │ ## heading: <https://räksmörgås.josefsson.org/> 122 - 50 │ 123 - 51 │ # canonical urls 124 - 52 │ 125 - 53 │ found: <https://example.org/book/tests/ra-known-quirks> 126 - 54 │ 127 - 55 │ found: <https://example.org/book/tests/ra-known-quirks.html> 128 - 56 │ 129 - 57 │ missing: <https://example.org/book/404> 130 - · ───────────────┬────────────── 131 - · ╰── file does not exist at path: crates/mdbookkit/tests/404.md 132 - 58 │ 133 - ╰──── 134 - 135 - warning: no such fragment 136 - ╭─[crates/mdbookkit/tests/tests/link-forever.md:45:1] 137 - 44 │ 138 - 45 │ [associated items](../tests/ra-known-quirks.md#associated_items_on_primitive_types) 139 - · ─────────────────────────────────────────┬───────────────────────────────────────── 140 - · ╰── #associated_items_on_primitive_types not found in crates/mdbookkit/tests/tests/ra-known-quirks.md 141 - 46 │ 142 - ╰────

+22

crates/mdbookkit/tests/snaps/link_forever/ra-known-quirks.snap

··· 1 + --- 2 + source: crates/mdbookkit/tests/link_forever.rs 3 + expression: output 4 + --- 5 + # primitive types resolved to nightly 6 + 7 + - [u8] 8 + - [u32] 9 + - [f64] 10 + - [char] 11 + - [str] 12 + 13 + # associated items on primitive types 14 + 15 + - [str::parse] 16 + - [f64::MIN_POSITIVE] 17 + 18 + # macro_export 19 + 20 + - [std::vec!] 21 + - [std::format!] 22 + - [tokio::main!]

+9 -5

crates/mdbookkit/tests/tests/link-forever.md

··· 1 1 # relative paths 2 2 3 - [Cargo.toml](../../Cargo.toml) 4 - 5 - [src/lib.rs](../../src/lib.rs) 3 + [Cargo.toml](../../../../Cargo.toml) 6 4 7 5 ![error reporting](../../../../docs/src/rustdoc-link/media/error-reporting.png) 8 6 ··· 19 17 [link_forever.rs](../link_forever.rs) 20 18 21 19 ![selfie](Macaca_nigra_self-portrait_large.jpg) 22 - 23 - <https://commons.wikimedia.org/wiki/File:Macaca_nigra_self-portrait_large.jpg> 24 20 25 21 # fragments 26 22 ··· 57 53 missing: <https://example.org/book/404> 58 54 59 55 ignored: <https://example.com/book/ra-known-quirks> 56 + 57 + # image-in-link 58 + 59 + [![crates.io](https://img.shields.io/crates/v/mdbookkit?style=flat-square)](https://crates.io/crates/mdbookkit) 60 + 61 + [![selfie](/crates/mdbookkit/tests/tests/Macaca_nigra_self-portrait_large.jpg)](https://commons.wikimedia.org/wiki/File:Macaca_nigra_self-portrait_large.jpg) 62 + 63 + [![selfie](/crates/mdbookkit/tests/tests/Macaca_nigra_self-portrait_large.jpg) <br> Self-portrait of a female Macaca nigra in North Sulawesi (2011)](/crates/mdbookkit/tests/tests/Macaca_nigra_self-portrait_large.jpg)

docs/app/socials.pxd

This is a binary file and will not be displayed.

+1 -1

docs/book.toml

··· 56 56 command = "cargo bin mdbook-alerts" 57 57 58 58 [preprocessor.app] 59 - command = "deno run -A app/build/preprocessor.ts" 59 + command = "deno run --allow-all app/build/preprocessor.ts" 60 60 61 61 [_metadata] 62 62 base-url = "https://tonywu6.github.io/mdbookkit/"

+3 -3

docs/src/link-forever/working-with-include.md

··· 1 1 # Working with `{{#include}}` 2 2 3 - mdBook provides an [`{{#include}}` directive][mdbook-include] that you can embed files 4 - in book pages. If the embedded content also contains path-based links, then some extra 5 - care may be needed: 3 + mdBook provides an [`{{#include}}` directive][mdbook-include] for embedding files in 4 + book pages. If the embedded content also contains path-based links, then some extra care 5 + may be needed: 6 6 7 7 - The preprocessor does not resolve links relative to the file being included (because 8 8 it doesn't have enough information to do so). In this case, relative paths could be

docs/src/media/banner.webp

This is a binary file and will not be displayed.

+10 -2

utils/mdbook-socials/src/main.rs

··· 1 - //! Postprocess mdBook HTML output to add OpenGraph metadata, for social images, etc. 1 + //! Postprocess mdBook HTML output. 2 + //! 3 + //! Currently does the following: 4 + //! 5 + //! - Add OpenGraph metadata and link to images for social. 6 + //! - Add explicit widths and heights to images: <https://web.dev/articles/optimize-cls#images-without-dimensions> 2 7 //! 3 8 //! mdBook doesn't support frontmatters yet, so this cannot be a preprocessor. 4 9 ··· 165 170 element!(r#"img[src]"#, |elem| { 166 171 let src = elem.get_attribute("src").unwrap(); 167 172 let src = url.join(&src)?; 168 - let img = image::open(src.to_file_path().unwrap())?; 173 + let img = image::open(match src.to_file_path() { 174 + Ok(path) => path, 175 + Err(()) => return Ok(()), 176 + })?; 169 177 elem.set_attribute("width", &img.width().to_string())?; 170 178 elem.set_attribute("height", &img.height().to_string())?; 171 179 Ok(())

Configure Feed

Configure Feed