]> git.lizzy.rs Git - rust.git/blob - src/librustdoc/html/markdown.rs
Auto merge of #88717 - tabokie:vecdeque-fast-append, r=m-ou-se
[rust.git] / src / librustdoc / html / markdown.rs
1 //! Markdown formatting for rustdoc.
2 //!
3 //! This module implements markdown formatting through the pulldown-cmark library.
4 //!
5 //! ```
6 //! #![feature(rustc_private)]
7 //!
8 //! extern crate rustc_span;
9 //!
10 //! use rustc_span::edition::Edition;
11 //! use rustdoc::html::markdown::{HeadingOffset, IdMap, Markdown, ErrorCodes};
12 //!
13 //! let s = "My *markdown* _text_";
14 //! let mut id_map = IdMap::new();
15 //! let md = Markdown {
16 //!     content: s,
17 //!     links: &[],
18 //!     ids: &mut id_map,
19 //!     error_codes: ErrorCodes::Yes,
20 //!     edition: Edition::Edition2015,
21 //!     playground: &None,
22 //!     heading_offset: HeadingOffset::H2,
23 //! };
24 //! let html = md.into_string();
25 //! // ... something using html
26 //! ```
27
28 use rustc_data_structures::fx::FxHashMap;
29 use rustc_hir::def_id::DefId;
30 use rustc_hir::HirId;
31 use rustc_middle::ty::TyCtxt;
32 use rustc_span::edition::Edition;
33 use rustc_span::Span;
34
35 use std::borrow::Cow;
36 use std::cell::RefCell;
37 use std::collections::VecDeque;
38 use std::default::Default;
39 use std::fmt::Write;
40 use std::ops::{ControlFlow, Range};
41 use std::str;
42
43 use crate::clean::RenderedLink;
44 use crate::doctest;
45 use crate::html::escape::Escape;
46 use crate::html::format::Buffer;
47 use crate::html::highlight;
48 use crate::html::length_limit::HtmlWithLimit;
49 use crate::html::toc::TocBuilder;
50
51 use pulldown_cmark::{
52     html, BrokenLink, CodeBlockKind, CowStr, Event, LinkType, Options, Parser, Tag,
53 };
54
55 #[cfg(test)]
56 mod tests;
57
58 const MAX_HEADER_LEVEL: u32 = 6;
59
60 /// Options for rendering Markdown in the main body of documentation.
61 pub(crate) fn main_body_opts() -> Options {
62     Options::ENABLE_TABLES
63         | Options::ENABLE_FOOTNOTES
64         | Options::ENABLE_STRIKETHROUGH
65         | Options::ENABLE_TASKLISTS
66         | Options::ENABLE_SMART_PUNCTUATION
67 }
68
69 /// Options for rendering Markdown in summaries (e.g., in search results).
70 pub(crate) fn summary_opts() -> Options {
71     Options::ENABLE_TABLES
72         | Options::ENABLE_FOOTNOTES
73         | Options::ENABLE_STRIKETHROUGH
74         | Options::ENABLE_TASKLISTS
75         | Options::ENABLE_SMART_PUNCTUATION
76 }
77
78 #[derive(Debug, Clone, Copy)]
79 pub enum HeadingOffset {
80     H1 = 0,
81     H2,
82     H3,
83     H4,
84     H5,
85     H6,
86 }
87
88 /// When `to_string` is called, this struct will emit the HTML corresponding to
89 /// the rendered version of the contained markdown string.
90 pub struct Markdown<'a> {
91     pub content: &'a str,
92     /// A list of link replacements.
93     pub links: &'a [RenderedLink],
94     /// The current list of used header IDs.
95     pub ids: &'a mut IdMap,
96     /// Whether to allow the use of explicit error codes in doctest lang strings.
97     pub error_codes: ErrorCodes,
98     /// Default edition to use when parsing doctests (to add a `fn main`).
99     pub edition: Edition,
100     pub playground: &'a Option<Playground>,
101     /// Offset at which we render headings.
102     /// E.g. if `heading_offset: HeadingOffset::H2`, then `# something` renders an `<h2>`.
103     pub heading_offset: HeadingOffset,
104 }
105 /// A tuple struct like `Markdown` that renders the markdown with a table of contents.
106 crate struct MarkdownWithToc<'a>(
107     crate &'a str,
108     crate &'a mut IdMap,
109     crate ErrorCodes,
110     crate Edition,
111     crate &'a Option<Playground>,
112 );
113 /// A tuple struct like `Markdown` that renders the markdown escaping HTML tags.
114 crate struct MarkdownHtml<'a>(
115     crate &'a str,
116     crate &'a mut IdMap,
117     crate ErrorCodes,
118     crate Edition,
119     crate &'a Option<Playground>,
120 );
121 /// A tuple struct like `Markdown` that renders only the first paragraph.
122 crate struct MarkdownSummaryLine<'a>(pub &'a str, pub &'a [RenderedLink]);
123
124 #[derive(Copy, Clone, PartialEq, Debug)]
125 pub enum ErrorCodes {
126     Yes,
127     No,
128 }
129
130 impl ErrorCodes {
131     crate fn from(b: bool) -> Self {
132         match b {
133             true => ErrorCodes::Yes,
134             false => ErrorCodes::No,
135         }
136     }
137
138     crate fn as_bool(self) -> bool {
139         match self {
140             ErrorCodes::Yes => true,
141             ErrorCodes::No => false,
142         }
143     }
144 }
145
146 /// Controls whether a line will be hidden or shown in HTML output.
147 ///
148 /// All lines are used in documentation tests.
149 enum Line<'a> {
150     Hidden(&'a str),
151     Shown(Cow<'a, str>),
152 }
153
154 impl<'a> Line<'a> {
155     fn for_html(self) -> Option<Cow<'a, str>> {
156         match self {
157             Line::Shown(l) => Some(l),
158             Line::Hidden(_) => None,
159         }
160     }
161
162     fn for_code(self) -> Cow<'a, str> {
163         match self {
164             Line::Shown(l) => l,
165             Line::Hidden(l) => Cow::Borrowed(l),
166         }
167     }
168 }
169
170 // FIXME: There is a minor inconsistency here. For lines that start with ##, we
171 // have no easy way of removing a potential single space after the hashes, which
172 // is done in the single # case. This inconsistency seems okay, if non-ideal. In
173 // order to fix it we'd have to iterate to find the first non-# character, and
174 // then reallocate to remove it; which would make us return a String.
175 fn map_line(s: &str) -> Line<'_> {
176     let trimmed = s.trim();
177     if trimmed.starts_with("##") {
178         Line::Shown(Cow::Owned(s.replacen("##", "#", 1)))
179     } else if let Some(stripped) = trimmed.strip_prefix("# ") {
180         // # text
181         Line::Hidden(&stripped)
182     } else if trimmed == "#" {
183         // We cannot handle '#text' because it could be #[attr].
184         Line::Hidden("")
185     } else {
186         Line::Shown(Cow::Borrowed(s))
187     }
188 }
189
190 /// Convert chars from a title for an id.
191 ///
192 /// "Hello, world!" -> "hello-world"
193 fn slugify(c: char) -> Option<char> {
194     if c.is_alphanumeric() || c == '-' || c == '_' {
195         if c.is_ascii() { Some(c.to_ascii_lowercase()) } else { Some(c) }
196     } else if c.is_whitespace() && c.is_ascii() {
197         Some('-')
198     } else {
199         None
200     }
201 }
202
203 #[derive(Clone, Debug)]
204 pub struct Playground {
205     pub crate_name: Option<String>,
206     pub url: String,
207 }
208
209 /// Adds syntax highlighting and playground Run buttons to Rust code blocks.
210 struct CodeBlocks<'p, 'a, I: Iterator<Item = Event<'a>>> {
211     inner: I,
212     check_error_codes: ErrorCodes,
213     edition: Edition,
214     // Information about the playground if a URL has been specified, containing an
215     // optional crate name and the URL.
216     playground: &'p Option<Playground>,
217 }
218
219 impl<'p, 'a, I: Iterator<Item = Event<'a>>> CodeBlocks<'p, 'a, I> {
220     fn new(
221         iter: I,
222         error_codes: ErrorCodes,
223         edition: Edition,
224         playground: &'p Option<Playground>,
225     ) -> Self {
226         CodeBlocks { inner: iter, check_error_codes: error_codes, edition, playground }
227     }
228 }
229
230 impl<'a, I: Iterator<Item = Event<'a>>> Iterator for CodeBlocks<'_, 'a, I> {
231     type Item = Event<'a>;
232
233     fn next(&mut self) -> Option<Self::Item> {
234         let event = self.inner.next();
235         let compile_fail;
236         let should_panic;
237         let ignore;
238         let edition;
239         let kind = if let Some(Event::Start(Tag::CodeBlock(kind))) = event {
240             kind
241         } else {
242             return event;
243         };
244
245         let mut origtext = String::new();
246         for event in &mut self.inner {
247             match event {
248                 Event::End(Tag::CodeBlock(..)) => break,
249                 Event::Text(ref s) => {
250                     origtext.push_str(s);
251                 }
252                 _ => {}
253             }
254         }
255         let lines = origtext.lines().filter_map(|l| map_line(l).for_html());
256         let text = lines.collect::<Vec<Cow<'_, str>>>().join("\n");
257
258         let parse_result = match kind {
259             CodeBlockKind::Fenced(ref lang) => {
260                 let parse_result =
261                     LangString::parse_without_check(&lang, self.check_error_codes, false);
262                 if !parse_result.rust {
263                     return Some(Event::Html(
264                         format!(
265                             "<div class=\"example-wrap\">\
266                                  <pre class=\"language-{}\"><code>{}</code></pre>\
267                              </div>",
268                             lang,
269                             Escape(&text),
270                         )
271                         .into(),
272                     ));
273                 }
274                 parse_result
275             }
276             CodeBlockKind::Indented => Default::default(),
277         };
278
279         compile_fail = parse_result.compile_fail;
280         should_panic = parse_result.should_panic;
281         ignore = parse_result.ignore;
282         edition = parse_result.edition;
283
284         let explicit_edition = edition.is_some();
285         let edition = edition.unwrap_or(self.edition);
286
287         let playground_button = self.playground.as_ref().and_then(|playground| {
288             let krate = &playground.crate_name;
289             let url = &playground.url;
290             if url.is_empty() {
291                 return None;
292             }
293             let test = origtext
294                 .lines()
295                 .map(|l| map_line(l).for_code())
296                 .collect::<Vec<Cow<'_, str>>>()
297                 .join("\n");
298             let krate = krate.as_ref().map(|s| &**s);
299             let (test, _, _) =
300                 doctest::make_test(&test, krate, false, &Default::default(), edition, None);
301             let channel = if test.contains("#![feature(") { "&amp;version=nightly" } else { "" };
302
303             let edition_string = format!("&amp;edition={}", edition);
304
305             // These characters don't need to be escaped in a URI.
306             // FIXME: use a library function for percent encoding.
307             fn dont_escape(c: u8) -> bool {
308                 (b'a' <= c && c <= b'z')
309                     || (b'A' <= c && c <= b'Z')
310                     || (b'0' <= c && c <= b'9')
311                     || c == b'-'
312                     || c == b'_'
313                     || c == b'.'
314                     || c == b'~'
315                     || c == b'!'
316                     || c == b'\''
317                     || c == b'('
318                     || c == b')'
319                     || c == b'*'
320             }
321             let mut test_escaped = String::new();
322             for b in test.bytes() {
323                 if dont_escape(b) {
324                     test_escaped.push(char::from(b));
325                 } else {
326                     write!(test_escaped, "%{:02X}", b).unwrap();
327                 }
328             }
329             Some(format!(
330                 r#"<a class="test-arrow" target="_blank" href="{}?code={}{}{}">Run</a>"#,
331                 url, test_escaped, channel, edition_string
332             ))
333         });
334
335         let tooltip = if ignore != Ignore::None {
336             Some((None, "ignore"))
337         } else if compile_fail {
338             Some((None, "compile_fail"))
339         } else if should_panic {
340             Some((None, "should_panic"))
341         } else if explicit_edition {
342             Some((Some(edition), "edition"))
343         } else {
344             None
345         };
346
347         // insert newline to clearly separate it from the
348         // previous block so we can shorten the html output
349         let mut s = Buffer::new();
350         s.push_str("\n");
351         highlight::render_with_highlighting(
352             &text,
353             &mut s,
354             Some(&format!(
355                 "rust-example-rendered{}",
356                 if let Some((_, class)) = tooltip { format!(" {}", class) } else { String::new() }
357             )),
358             playground_button.as_deref(),
359             tooltip,
360             edition,
361             None,
362             None,
363         );
364         Some(Event::Html(s.into_inner().into()))
365     }
366 }
367
368 /// Make headings links with anchor IDs and build up TOC.
369 struct LinkReplacer<'a, I: Iterator<Item = Event<'a>>> {
370     inner: I,
371     links: &'a [RenderedLink],
372     shortcut_link: Option<&'a RenderedLink>,
373 }
374
375 impl<'a, I: Iterator<Item = Event<'a>>> LinkReplacer<'a, I> {
376     fn new(iter: I, links: &'a [RenderedLink]) -> Self {
377         LinkReplacer { inner: iter, links, shortcut_link: None }
378     }
379 }
380
381 impl<'a, I: Iterator<Item = Event<'a>>> Iterator for LinkReplacer<'a, I> {
382     type Item = Event<'a>;
383
384     fn next(&mut self) -> Option<Self::Item> {
385         let mut event = self.inner.next();
386
387         // Replace intra-doc links and remove disambiguators from shortcut links (`[fn@f]`).
388         match &mut event {
389             // This is a shortcut link that was resolved by the broken_link_callback: `[fn@f]`
390             // Remove any disambiguator.
391             Some(Event::Start(Tag::Link(
392                 // [fn@f] or [fn@f][]
393                 LinkType::ShortcutUnknown | LinkType::CollapsedUnknown,
394                 dest,
395                 title,
396             ))) => {
397                 debug!("saw start of shortcut link to {} with title {}", dest, title);
398                 // If this is a shortcut link, it was resolved by the broken_link_callback.
399                 // So the URL will already be updated properly.
400                 let link = self.links.iter().find(|&link| *link.href == **dest);
401                 // Since this is an external iterator, we can't replace the inner text just yet.
402                 // Store that we saw a link so we know to replace it later.
403                 if let Some(link) = link {
404                     trace!("it matched");
405                     assert!(self.shortcut_link.is_none(), "shortcut links cannot be nested");
406                     self.shortcut_link = Some(link);
407                 }
408             }
409             // Now that we're done with the shortcut link, don't replace any more text.
410             Some(Event::End(Tag::Link(
411                 LinkType::ShortcutUnknown | LinkType::CollapsedUnknown,
412                 dest,
413                 _,
414             ))) => {
415                 debug!("saw end of shortcut link to {}", dest);
416                 if self.links.iter().any(|link| *link.href == **dest) {
417                     assert!(self.shortcut_link.is_some(), "saw closing link without opening tag");
418                     self.shortcut_link = None;
419                 }
420             }
421             // Handle backticks in inline code blocks, but only if we're in the middle of a shortcut link.
422             // [`fn@f`]
423             Some(Event::Code(text)) => {
424                 trace!("saw code {}", text);
425                 if let Some(link) = self.shortcut_link {
426                     trace!("original text was {}", link.original_text);
427                     // NOTE: this only replaces if the code block is the *entire* text.
428                     // If only part of the link has code highlighting, the disambiguator will not be removed.
429                     // e.g. [fn@`f`]
430                     // This is a limitation from `collect_intra_doc_links`: it passes a full link,
431                     // and does not distinguish at all between code blocks.
432                     // So we could never be sure we weren't replacing too much:
433                     // [fn@my_`f`unc] is treated the same as [my_func()] in that pass.
434                     //
435                     // NOTE: &[1..len() - 1] is to strip the backticks
436                     if **text == link.original_text[1..link.original_text.len() - 1] {
437                         debug!("replacing {} with {}", text, link.new_text);
438                         *text = CowStr::Borrowed(&link.new_text);
439                     }
440                 }
441             }
442             // Replace plain text in links, but only in the middle of a shortcut link.
443             // [fn@f]
444             Some(Event::Text(text)) => {
445                 trace!("saw text {}", text);
446                 if let Some(link) = self.shortcut_link {
447                     trace!("original text was {}", link.original_text);
448                     // NOTE: same limitations as `Event::Code`
449                     if **text == *link.original_text {
450                         debug!("replacing {} with {}", text, link.new_text);
451                         *text = CowStr::Borrowed(&link.new_text);
452                     }
453                 }
454             }
455             // If this is a link, but not a shortcut link,
456             // replace the URL, since the broken_link_callback was not called.
457             Some(Event::Start(Tag::Link(_, dest, _))) => {
458                 if let Some(link) = self.links.iter().find(|&link| *link.original_text == **dest) {
459                     *dest = CowStr::Borrowed(link.href.as_ref());
460                 }
461             }
462             // Anything else couldn't have been a valid Rust path, so no need to replace the text.
463             _ => {}
464         }
465
466         // Yield the modified event
467         event
468     }
469 }
470
471 /// Wrap HTML tables into `<div>` to prevent having the doc blocks width being too big.
472 struct TableWrapper<'a, I: Iterator<Item = Event<'a>>> {
473     inner: I,
474     stored_events: VecDeque<Event<'a>>,
475 }
476
477 impl<'a, I: Iterator<Item = Event<'a>>> TableWrapper<'a, I> {
478     fn new(iter: I) -> Self {
479         Self { inner: iter, stored_events: VecDeque::new() }
480     }
481 }
482
483 impl<'a, I: Iterator<Item = Event<'a>>> Iterator for TableWrapper<'a, I> {
484     type Item = Event<'a>;
485
486     fn next(&mut self) -> Option<Self::Item> {
487         if let Some(first) = self.stored_events.pop_front() {
488             return Some(first);
489         }
490
491         let event = self.inner.next()?;
492
493         Some(match event {
494             Event::Start(Tag::Table(t)) => {
495                 self.stored_events.push_back(Event::Start(Tag::Table(t)));
496                 Event::Html(CowStr::Borrowed("<div>"))
497             }
498             Event::End(Tag::Table(t)) => {
499                 self.stored_events.push_back(Event::Html(CowStr::Borrowed("</div>")));
500                 Event::End(Tag::Table(t))
501             }
502             e => e,
503         })
504     }
505 }
506
507 type SpannedEvent<'a> = (Event<'a>, Range<usize>);
508
509 /// Make headings links with anchor IDs and build up TOC.
510 struct HeadingLinks<'a, 'b, 'ids, I> {
511     inner: I,
512     toc: Option<&'b mut TocBuilder>,
513     buf: VecDeque<SpannedEvent<'a>>,
514     id_map: &'ids mut IdMap,
515     heading_offset: HeadingOffset,
516 }
517
518 impl<'a, 'b, 'ids, I> HeadingLinks<'a, 'b, 'ids, I> {
519     fn new(
520         iter: I,
521         toc: Option<&'b mut TocBuilder>,
522         ids: &'ids mut IdMap,
523         heading_offset: HeadingOffset,
524     ) -> Self {
525         HeadingLinks { inner: iter, toc, buf: VecDeque::new(), id_map: ids, heading_offset }
526     }
527 }
528
529 impl<'a, 'b, 'ids, I: Iterator<Item = SpannedEvent<'a>>> Iterator
530     for HeadingLinks<'a, 'b, 'ids, I>
531 {
532     type Item = SpannedEvent<'a>;
533
534     fn next(&mut self) -> Option<Self::Item> {
535         if let Some(e) = self.buf.pop_front() {
536             return Some(e);
537         }
538
539         let event = self.inner.next();
540         if let Some((Event::Start(Tag::Heading(level)), _)) = event {
541             let mut id = String::new();
542             for event in &mut self.inner {
543                 match &event.0 {
544                     Event::End(Tag::Heading(..)) => break,
545                     Event::Start(Tag::Link(_, _, _)) | Event::End(Tag::Link(..)) => {}
546                     Event::Text(text) | Event::Code(text) => {
547                         id.extend(text.chars().filter_map(slugify));
548                         self.buf.push_back(event);
549                     }
550                     _ => self.buf.push_back(event),
551                 }
552             }
553             let id = self.id_map.derive(id);
554
555             if let Some(ref mut builder) = self.toc {
556                 let mut html_header = String::new();
557                 html::push_html(&mut html_header, self.buf.iter().map(|(ev, _)| ev.clone()));
558                 let sec = builder.push(level as u32, html_header, id.clone());
559                 self.buf.push_front((Event::Html(format!("{} ", sec).into()), 0..0));
560             }
561
562             let level = std::cmp::min(level + (self.heading_offset as u32), MAX_HEADER_LEVEL);
563             self.buf.push_back((Event::Html(format!("</a></h{}>", level).into()), 0..0));
564
565             let start_tags = format!(
566                 "<h{level} id=\"{id}\" class=\"section-header\">\
567                     <a href=\"#{id}\">",
568                 id = id,
569                 level = level
570             );
571             return Some((Event::Html(start_tags.into()), 0..0));
572         }
573         event
574     }
575 }
576
577 /// Extracts just the first paragraph.
578 struct SummaryLine<'a, I: Iterator<Item = Event<'a>>> {
579     inner: I,
580     started: bool,
581     depth: u32,
582 }
583
584 impl<'a, I: Iterator<Item = Event<'a>>> SummaryLine<'a, I> {
585     fn new(iter: I) -> Self {
586         SummaryLine { inner: iter, started: false, depth: 0 }
587     }
588 }
589
590 fn check_if_allowed_tag(t: &Tag<'_>) -> bool {
591     matches!(
592         t,
593         Tag::Paragraph | Tag::Item | Tag::Emphasis | Tag::Strong | Tag::Link(..) | Tag::BlockQuote
594     )
595 }
596
597 fn is_forbidden_tag(t: &Tag<'_>) -> bool {
598     matches!(t, Tag::CodeBlock(_) | Tag::Table(_) | Tag::TableHead | Tag::TableRow | Tag::TableCell)
599 }
600
601 impl<'a, I: Iterator<Item = Event<'a>>> Iterator for SummaryLine<'a, I> {
602     type Item = Event<'a>;
603
604     fn next(&mut self) -> Option<Self::Item> {
605         if self.started && self.depth == 0 {
606             return None;
607         }
608         if !self.started {
609             self.started = true;
610         }
611         if let Some(event) = self.inner.next() {
612             let mut is_start = true;
613             let is_allowed_tag = match event {
614                 Event::Start(ref c) => {
615                     if is_forbidden_tag(c) {
616                         return None;
617                     }
618                     self.depth += 1;
619                     check_if_allowed_tag(c)
620                 }
621                 Event::End(ref c) => {
622                     if is_forbidden_tag(c) {
623                         return None;
624                     }
625                     self.depth -= 1;
626                     is_start = false;
627                     check_if_allowed_tag(c)
628                 }
629                 _ => true,
630             };
631             return if !is_allowed_tag {
632                 if is_start {
633                     Some(Event::Start(Tag::Paragraph))
634                 } else {
635                     Some(Event::End(Tag::Paragraph))
636                 }
637             } else {
638                 Some(event)
639             };
640         }
641         None
642     }
643 }
644
645 /// Moves all footnote definitions to the end and add back links to the
646 /// references.
647 struct Footnotes<'a, I> {
648     inner: I,
649     footnotes: FxHashMap<String, (Vec<Event<'a>>, u16)>,
650 }
651
652 impl<'a, I> Footnotes<'a, I> {
653     fn new(iter: I) -> Self {
654         Footnotes { inner: iter, footnotes: FxHashMap::default() }
655     }
656
657     fn get_entry(&mut self, key: &str) -> &mut (Vec<Event<'a>>, u16) {
658         let new_id = self.footnotes.keys().count() + 1;
659         let key = key.to_owned();
660         self.footnotes.entry(key).or_insert((Vec::new(), new_id as u16))
661     }
662 }
663
664 impl<'a, I: Iterator<Item = SpannedEvent<'a>>> Iterator for Footnotes<'a, I> {
665     type Item = SpannedEvent<'a>;
666
667     fn next(&mut self) -> Option<Self::Item> {
668         loop {
669             match self.inner.next() {
670                 Some((Event::FootnoteReference(ref reference), range)) => {
671                     let entry = self.get_entry(&reference);
672                     let reference = format!(
673                         "<sup id=\"fnref{0}\"><a href=\"#fn{0}\">{0}</a></sup>",
674                         (*entry).1
675                     );
676                     return Some((Event::Html(reference.into()), range));
677                 }
678                 Some((Event::Start(Tag::FootnoteDefinition(def)), _)) => {
679                     let mut content = Vec::new();
680                     for (event, _) in &mut self.inner {
681                         if let Event::End(Tag::FootnoteDefinition(..)) = event {
682                             break;
683                         }
684                         content.push(event);
685                     }
686                     let entry = self.get_entry(&def);
687                     (*entry).0 = content;
688                 }
689                 Some(e) => return Some(e),
690                 None => {
691                     if !self.footnotes.is_empty() {
692                         let mut v: Vec<_> = self.footnotes.drain().map(|(_, x)| x).collect();
693                         v.sort_by(|a, b| a.1.cmp(&b.1));
694                         let mut ret = String::from("<div class=\"footnotes\"><hr><ol>");
695                         for (mut content, id) in v {
696                             write!(ret, "<li id=\"fn{}\">", id).unwrap();
697                             let mut is_paragraph = false;
698                             if let Some(&Event::End(Tag::Paragraph)) = content.last() {
699                                 content.pop();
700                                 is_paragraph = true;
701                             }
702                             html::push_html(&mut ret, content.into_iter());
703                             write!(ret, "&nbsp;<a href=\"#fnref{}\">↩</a>", id).unwrap();
704                             if is_paragraph {
705                                 ret.push_str("</p>");
706                             }
707                             ret.push_str("</li>");
708                         }
709                         ret.push_str("</ol></div>");
710                         return Some((Event::Html(ret.into()), 0..0));
711                     } else {
712                         return None;
713                     }
714                 }
715             }
716         }
717     }
718 }
719
720 crate fn find_testable_code<T: doctest::Tester>(
721     doc: &str,
722     tests: &mut T,
723     error_codes: ErrorCodes,
724     enable_per_target_ignores: bool,
725     extra_info: Option<&ExtraInfo<'_>>,
726 ) {
727     let mut parser = Parser::new(doc).into_offset_iter();
728     let mut prev_offset = 0;
729     let mut nb_lines = 0;
730     let mut register_header = None;
731     while let Some((event, offset)) = parser.next() {
732         match event {
733             Event::Start(Tag::CodeBlock(kind)) => {
734                 let block_info = match kind {
735                     CodeBlockKind::Fenced(ref lang) => {
736                         if lang.is_empty() {
737                             Default::default()
738                         } else {
739                             LangString::parse(
740                                 lang,
741                                 error_codes,
742                                 enable_per_target_ignores,
743                                 extra_info,
744                             )
745                         }
746                     }
747                     CodeBlockKind::Indented => Default::default(),
748                 };
749                 if !block_info.rust {
750                     continue;
751                 }
752
753                 let mut test_s = String::new();
754
755                 while let Some((Event::Text(s), _)) = parser.next() {
756                     test_s.push_str(&s);
757                 }
758                 let text = test_s
759                     .lines()
760                     .map(|l| map_line(l).for_code())
761                     .collect::<Vec<Cow<'_, str>>>()
762                     .join("\n");
763
764                 nb_lines += doc[prev_offset..offset.start].lines().count();
765                 // If there are characters between the preceding line ending and
766                 // this code block, `str::lines` will return an additional line,
767                 // which we subtract here.
768                 if nb_lines != 0 && !&doc[prev_offset..offset.start].ends_with("\n") {
769                     nb_lines -= 1;
770                 }
771                 let line = tests.get_line() + nb_lines + 1;
772                 tests.add_test(text, block_info, line);
773                 prev_offset = offset.start;
774             }
775             Event::Start(Tag::Heading(level)) => {
776                 register_header = Some(level as u32);
777             }
778             Event::Text(ref s) if register_header.is_some() => {
779                 let level = register_header.unwrap();
780                 if s.is_empty() {
781                     tests.register_header("", level);
782                 } else {
783                     tests.register_header(s, level);
784                 }
785                 register_header = None;
786             }
787             _ => {}
788         }
789     }
790 }
791
792 crate struct ExtraInfo<'tcx> {
793     id: ExtraInfoId,
794     sp: Span,
795     tcx: TyCtxt<'tcx>,
796 }
797
798 enum ExtraInfoId {
799     Hir(HirId),
800     Def(DefId),
801 }
802
803 impl<'tcx> ExtraInfo<'tcx> {
804     crate fn new(tcx: TyCtxt<'tcx>, hir_id: HirId, sp: Span) -> ExtraInfo<'tcx> {
805         ExtraInfo { id: ExtraInfoId::Hir(hir_id), sp, tcx }
806     }
807
808     crate fn new_did(tcx: TyCtxt<'tcx>, did: DefId, sp: Span) -> ExtraInfo<'tcx> {
809         ExtraInfo { id: ExtraInfoId::Def(did), sp, tcx }
810     }
811
812     fn error_invalid_codeblock_attr(&self, msg: &str, help: &str) {
813         let hir_id = match self.id {
814             ExtraInfoId::Hir(hir_id) => hir_id,
815             ExtraInfoId::Def(item_did) => {
816                 match item_did.as_local() {
817                     Some(item_did) => self.tcx.hir().local_def_id_to_hir_id(item_did),
818                     None => {
819                         // If non-local, no need to check anything.
820                         return;
821                     }
822                 }
823             }
824         };
825         self.tcx.struct_span_lint_hir(
826             crate::lint::INVALID_CODEBLOCK_ATTRIBUTES,
827             hir_id,
828             self.sp,
829             |lint| {
830                 let mut diag = lint.build(msg);
831                 diag.help(help);
832                 diag.emit();
833             },
834         );
835     }
836 }
837
838 #[derive(Eq, PartialEq, Clone, Debug)]
839 crate struct LangString {
840     original: String,
841     crate should_panic: bool,
842     crate no_run: bool,
843     crate ignore: Ignore,
844     crate rust: bool,
845     crate test_harness: bool,
846     crate compile_fail: bool,
847     crate error_codes: Vec<String>,
848     crate allow_fail: bool,
849     crate edition: Option<Edition>,
850 }
851
852 #[derive(Eq, PartialEq, Clone, Debug)]
853 crate enum Ignore {
854     All,
855     None,
856     Some(Vec<String>),
857 }
858
859 impl Default for LangString {
860     fn default() -> Self {
861         Self {
862             original: String::new(),
863             should_panic: false,
864             no_run: false,
865             ignore: Ignore::None,
866             rust: true,
867             test_harness: false,
868             compile_fail: false,
869             error_codes: Vec::new(),
870             allow_fail: false,
871             edition: None,
872         }
873     }
874 }
875
876 impl LangString {
877     fn parse_without_check(
878         string: &str,
879         allow_error_code_check: ErrorCodes,
880         enable_per_target_ignores: bool,
881     ) -> LangString {
882         Self::parse(string, allow_error_code_check, enable_per_target_ignores, None)
883     }
884
885     fn tokens(string: &str) -> impl Iterator<Item = &str> {
886         // Pandoc, which Rust once used for generating documentation,
887         // expects lang strings to be surrounded by `{}` and for each token
888         // to be proceeded by a `.`. Since some of these lang strings are still
889         // loose in the wild, we strip a pair of surrounding `{}` from the lang
890         // string and a leading `.` from each token.
891
892         let string = string.trim();
893
894         let first = string.chars().next();
895         let last = string.chars().last();
896
897         let string = if first == Some('{') && last == Some('}') {
898             &string[1..string.len() - 1]
899         } else {
900             string
901         };
902
903         string
904             .split(|c| c == ',' || c == ' ' || c == '\t')
905             .map(str::trim)
906             .map(|token| if token.chars().next() == Some('.') { &token[1..] } else { token })
907             .filter(|token| !token.is_empty())
908     }
909
910     fn parse(
911         string: &str,
912         allow_error_code_check: ErrorCodes,
913         enable_per_target_ignores: bool,
914         extra: Option<&ExtraInfo<'_>>,
915     ) -> LangString {
916         let allow_error_code_check = allow_error_code_check.as_bool();
917         let mut seen_rust_tags = false;
918         let mut seen_other_tags = false;
919         let mut data = LangString::default();
920         let mut ignores = vec![];
921
922         data.original = string.to_owned();
923
924         let tokens = Self::tokens(string).collect::<Vec<&str>>();
925
926         for token in tokens {
927             match token {
928                 "should_panic" => {
929                     data.should_panic = true;
930                     seen_rust_tags = !seen_other_tags;
931                 }
932                 "no_run" => {
933                     data.no_run = true;
934                     seen_rust_tags = !seen_other_tags;
935                 }
936                 "ignore" => {
937                     data.ignore = Ignore::All;
938                     seen_rust_tags = !seen_other_tags;
939                 }
940                 x if x.starts_with("ignore-") => {
941                     if enable_per_target_ignores {
942                         ignores.push(x.trim_start_matches("ignore-").to_owned());
943                         seen_rust_tags = !seen_other_tags;
944                     }
945                 }
946                 "allow_fail" => {
947                     data.allow_fail = true;
948                     seen_rust_tags = !seen_other_tags;
949                 }
950                 "rust" => {
951                     data.rust = true;
952                     seen_rust_tags = true;
953                 }
954                 "test_harness" => {
955                     data.test_harness = true;
956                     seen_rust_tags = !seen_other_tags || seen_rust_tags;
957                 }
958                 "compile_fail" => {
959                     data.compile_fail = true;
960                     seen_rust_tags = !seen_other_tags || seen_rust_tags;
961                     data.no_run = true;
962                 }
963                 x if x.starts_with("edition") => {
964                     data.edition = x[7..].parse::<Edition>().ok();
965                 }
966                 x if allow_error_code_check && x.starts_with('E') && x.len() == 5 => {
967                     if x[1..].parse::<u32>().is_ok() {
968                         data.error_codes.push(x.to_owned());
969                         seen_rust_tags = !seen_other_tags || seen_rust_tags;
970                     } else {
971                         seen_other_tags = true;
972                     }
973                 }
974                 x if extra.is_some() => {
975                     let s = x.to_lowercase();
976                     match if s == "compile-fail" || s == "compile_fail" || s == "compilefail" {
977                         Some((
978                             "compile_fail",
979                             "the code block will either not be tested if not marked as a rust one \
980                              or won't fail if it compiles successfully",
981                         ))
982                     } else if s == "should-panic" || s == "should_panic" || s == "shouldpanic" {
983                         Some((
984                             "should_panic",
985                             "the code block will either not be tested if not marked as a rust one \
986                              or won't fail if it doesn't panic when running",
987                         ))
988                     } else if s == "no-run" || s == "no_run" || s == "norun" {
989                         Some((
990                             "no_run",
991                             "the code block will either not be tested if not marked as a rust one \
992                              or will be run (which you might not want)",
993                         ))
994                     } else if s == "allow-fail" || s == "allow_fail" || s == "allowfail" {
995                         Some((
996                             "allow_fail",
997                             "the code block will either not be tested if not marked as a rust one \
998                              or will be run (which you might not want)",
999                         ))
1000                     } else if s == "test-harness" || s == "test_harness" || s == "testharness" {
1001                         Some((
1002                             "test_harness",
1003                             "the code block will either not be tested if not marked as a rust one \
1004                              or the code will be wrapped inside a main function",
1005                         ))
1006                     } else {
1007                         None
1008                     } {
1009                         Some((flag, help)) => {
1010                             if let Some(ref extra) = extra {
1011                                 extra.error_invalid_codeblock_attr(
1012                                     &format!("unknown attribute `{}`. Did you mean `{}`?", x, flag),
1013                                     help,
1014                                 );
1015                             }
1016                         }
1017                         None => {}
1018                     }
1019                     seen_other_tags = true;
1020                 }
1021                 _ => seen_other_tags = true,
1022             }
1023         }
1024
1025         // ignore-foo overrides ignore
1026         if !ignores.is_empty() {
1027             data.ignore = Ignore::Some(ignores);
1028         }
1029
1030         data.rust &= !seen_other_tags || seen_rust_tags;
1031
1032         data
1033     }
1034 }
1035
1036 impl Markdown<'_> {
1037     pub fn into_string(self) -> String {
1038         let Markdown {
1039             content: md,
1040             links,
1041             mut ids,
1042             error_codes: codes,
1043             edition,
1044             playground,
1045             heading_offset,
1046         } = self;
1047
1048         // This is actually common enough to special-case
1049         if md.is_empty() {
1050             return String::new();
1051         }
1052         let mut replacer = |broken_link: BrokenLink<'_>| {
1053             if let Some(link) =
1054                 links.iter().find(|link| &*link.original_text == broken_link.reference)
1055             {
1056                 Some((link.href.as_str().into(), link.new_text.as_str().into()))
1057             } else {
1058                 None
1059             }
1060         };
1061
1062         let p = Parser::new_with_broken_link_callback(md, main_body_opts(), Some(&mut replacer));
1063         let p = p.into_offset_iter();
1064
1065         let mut s = String::with_capacity(md.len() * 3 / 2);
1066
1067         let p = HeadingLinks::new(p, None, &mut ids, heading_offset);
1068         let p = Footnotes::new(p);
1069         let p = LinkReplacer::new(p.map(|(ev, _)| ev), links);
1070         let p = TableWrapper::new(p);
1071         let p = CodeBlocks::new(p, codes, edition, playground);
1072         html::push_html(&mut s, p);
1073
1074         s
1075     }
1076 }
1077
1078 impl MarkdownWithToc<'_> {
1079     crate fn into_string(self) -> String {
1080         let MarkdownWithToc(md, mut ids, codes, edition, playground) = self;
1081
1082         let p = Parser::new_ext(md, main_body_opts()).into_offset_iter();
1083
1084         let mut s = String::with_capacity(md.len() * 3 / 2);
1085
1086         let mut toc = TocBuilder::new();
1087
1088         {
1089             let p = HeadingLinks::new(p, Some(&mut toc), &mut ids, HeadingOffset::H1);
1090             let p = Footnotes::new(p);
1091             let p = TableWrapper::new(p.map(|(ev, _)| ev));
1092             let p = CodeBlocks::new(p, codes, edition, playground);
1093             html::push_html(&mut s, p);
1094         }
1095
1096         format!("<nav id=\"TOC\">{}</nav>{}", toc.into_toc().print(), s)
1097     }
1098 }
1099
1100 impl MarkdownHtml<'_> {
1101     crate fn into_string(self) -> String {
1102         let MarkdownHtml(md, mut ids, codes, edition, playground) = self;
1103
1104         // This is actually common enough to special-case
1105         if md.is_empty() {
1106             return String::new();
1107         }
1108         let p = Parser::new_ext(md, main_body_opts()).into_offset_iter();
1109
1110         // Treat inline HTML as plain text.
1111         let p = p.map(|event| match event.0 {
1112             Event::Html(text) => (Event::Text(text), event.1),
1113             _ => event,
1114         });
1115
1116         let mut s = String::with_capacity(md.len() * 3 / 2);
1117
1118         let p = HeadingLinks::new(p, None, &mut ids, HeadingOffset::H1);
1119         let p = Footnotes::new(p);
1120         let p = TableWrapper::new(p.map(|(ev, _)| ev));
1121         let p = CodeBlocks::new(p, codes, edition, playground);
1122         html::push_html(&mut s, p);
1123
1124         s
1125     }
1126 }
1127
1128 impl MarkdownSummaryLine<'_> {
1129     crate fn into_string(self) -> String {
1130         let MarkdownSummaryLine(md, links) = self;
1131         // This is actually common enough to special-case
1132         if md.is_empty() {
1133             return String::new();
1134         }
1135
1136         let mut replacer = |broken_link: BrokenLink<'_>| {
1137             if let Some(link) =
1138                 links.iter().find(|link| &*link.original_text == broken_link.reference)
1139             {
1140                 Some((link.href.as_str().into(), link.new_text.as_str().into()))
1141             } else {
1142                 None
1143             }
1144         };
1145
1146         let p = Parser::new_with_broken_link_callback(md, summary_opts(), Some(&mut replacer));
1147
1148         let mut s = String::new();
1149
1150         html::push_html(&mut s, LinkReplacer::new(SummaryLine::new(p), links));
1151
1152         s
1153     }
1154 }
1155
1156 /// Renders a subset of Markdown in the first paragraph of the provided Markdown.
1157 ///
1158 /// - *Italics*, **bold**, and `inline code` styles **are** rendered.
1159 /// - Headings and links are stripped (though the text *is* rendered).
1160 /// - HTML, code blocks, and everything else are ignored.
1161 ///
1162 /// Returns a tuple of the rendered HTML string and whether the output was shortened
1163 /// due to the provided `length_limit`.
1164 fn markdown_summary_with_limit(
1165     md: &str,
1166     link_names: &[RenderedLink],
1167     length_limit: usize,
1168 ) -> (String, bool) {
1169     if md.is_empty() {
1170         return (String::new(), false);
1171     }
1172
1173     let mut replacer = |broken_link: BrokenLink<'_>| {
1174         if let Some(link) =
1175             link_names.iter().find(|link| &*link.original_text == broken_link.reference)
1176         {
1177             Some((link.href.as_str().into(), link.new_text.as_str().into()))
1178         } else {
1179             None
1180         }
1181     };
1182
1183     let p = Parser::new_with_broken_link_callback(md, summary_opts(), Some(&mut replacer));
1184     let mut p = LinkReplacer::new(p, link_names);
1185
1186     let mut buf = HtmlWithLimit::new(length_limit);
1187     let mut stopped_early = false;
1188     p.try_for_each(|event| {
1189         match &event {
1190             Event::Text(text) => {
1191                 let r =
1192                     text.split_inclusive(char::is_whitespace).try_for_each(|word| buf.push(word));
1193                 if r.is_break() {
1194                     stopped_early = true;
1195                 }
1196                 return r;
1197             }
1198             Event::Code(code) => {
1199                 buf.open_tag("code");
1200                 let r = buf.push(code);
1201                 if r.is_break() {
1202                     stopped_early = true;
1203                 } else {
1204                     buf.close_tag();
1205                 }
1206                 return r;
1207             }
1208             Event::Start(tag) => match tag {
1209                 Tag::Emphasis => buf.open_tag("em"),
1210                 Tag::Strong => buf.open_tag("strong"),
1211                 Tag::CodeBlock(..) => return ControlFlow::BREAK,
1212                 _ => {}
1213             },
1214             Event::End(tag) => match tag {
1215                 Tag::Emphasis | Tag::Strong => buf.close_tag(),
1216                 Tag::Paragraph | Tag::Heading(..) => return ControlFlow::BREAK,
1217                 _ => {}
1218             },
1219             Event::HardBreak | Event::SoftBreak => buf.push(" ")?,
1220             _ => {}
1221         };
1222         ControlFlow::CONTINUE
1223     });
1224
1225     (buf.finish(), stopped_early)
1226 }
1227
1228 /// Renders a shortened first paragraph of the given Markdown as a subset of Markdown,
1229 /// making it suitable for contexts like the search index.
1230 ///
1231 /// Will shorten to 59 or 60 characters, including an ellipsis (…) if it was shortened.
1232 ///
1233 /// See [`markdown_summary_with_limit`] for details about what is rendered and what is not.
1234 crate fn short_markdown_summary(markdown: &str, link_names: &[RenderedLink]) -> String {
1235     let (mut s, was_shortened) = markdown_summary_with_limit(markdown, link_names, 59);
1236
1237     if was_shortened {
1238         s.push('…');
1239     }
1240
1241     s
1242 }
1243
1244 /// Renders the first paragraph of the provided markdown as plain text.
1245 /// Useful for alt-text.
1246 ///
1247 /// - Headings, links, and formatting are stripped.
1248 /// - Inline code is rendered as-is, surrounded by backticks.
1249 /// - HTML and code blocks are ignored.
1250 crate fn plain_text_summary(md: &str) -> String {
1251     if md.is_empty() {
1252         return String::new();
1253     }
1254
1255     let mut s = String::with_capacity(md.len() * 3 / 2);
1256
1257     for event in Parser::new_ext(md, summary_opts()) {
1258         match &event {
1259             Event::Text(text) => s.push_str(text),
1260             Event::Code(code) => {
1261                 s.push('`');
1262                 s.push_str(code);
1263                 s.push('`');
1264             }
1265             Event::HardBreak | Event::SoftBreak => s.push(' '),
1266             Event::Start(Tag::CodeBlock(..)) => break,
1267             Event::End(Tag::Paragraph) => break,
1268             Event::End(Tag::Heading(..)) => break,
1269             _ => (),
1270         }
1271     }
1272
1273     s
1274 }
1275
1276 #[derive(Debug)]
1277 crate struct MarkdownLink {
1278     pub kind: LinkType,
1279     pub link: String,
1280     pub range: Range<usize>,
1281 }
1282
1283 crate fn markdown_links(md: &str) -> Vec<MarkdownLink> {
1284     if md.is_empty() {
1285         return vec![];
1286     }
1287
1288     let links = RefCell::new(vec![]);
1289
1290     // FIXME: remove this function once pulldown_cmark can provide spans for link definitions.
1291     let locate = |s: &str, fallback: Range<usize>| unsafe {
1292         let s_start = s.as_ptr();
1293         let s_end = s_start.add(s.len());
1294         let md_start = md.as_ptr();
1295         let md_end = md_start.add(md.len());
1296         if md_start <= s_start && s_end <= md_end {
1297             let start = s_start.offset_from(md_start) as usize;
1298             let end = s_end.offset_from(md_start) as usize;
1299             start..end
1300         } else {
1301             fallback
1302         }
1303     };
1304
1305     let span_for_link = |link: &CowStr<'_>, span: Range<usize>| {
1306         // For diagnostics, we want to underline the link's definition but `span` will point at
1307         // where the link is used. This is a problem for reference-style links, where the definition
1308         // is separate from the usage.
1309         match link {
1310             // `Borrowed` variant means the string (the link's destination) may come directly from
1311             // the markdown text and we can locate the original link destination.
1312             // NOTE: LinkReplacer also provides `Borrowed` but possibly from other sources,
1313             // so `locate()` can fall back to use `span`.
1314             CowStr::Borrowed(s) => locate(s, span),
1315
1316             // For anything else, we can only use the provided range.
1317             CowStr::Boxed(_) | CowStr::Inlined(_) => span,
1318         }
1319     };
1320
1321     let mut push = |link: BrokenLink<'_>| {
1322         let span = span_for_link(&CowStr::Borrowed(link.reference), link.span);
1323         links.borrow_mut().push(MarkdownLink {
1324             kind: LinkType::ShortcutUnknown,
1325             link: link.reference.to_owned(),
1326             range: span,
1327         });
1328         None
1329     };
1330     let p = Parser::new_with_broken_link_callback(md, main_body_opts(), Some(&mut push))
1331         .into_offset_iter();
1332
1333     // There's no need to thread an IdMap through to here because
1334     // the IDs generated aren't going to be emitted anywhere.
1335     let mut ids = IdMap::new();
1336     let iter = Footnotes::new(HeadingLinks::new(p, None, &mut ids, HeadingOffset::H1));
1337
1338     for ev in iter {
1339         if let Event::Start(Tag::Link(kind, dest, _)) = ev.0 {
1340             debug!("found link: {}", dest);
1341             let span = span_for_link(&dest, ev.1);
1342             links.borrow_mut().push(MarkdownLink { kind, link: dest.into_string(), range: span });
1343         }
1344     }
1345
1346     links.into_inner()
1347 }
1348
1349 #[derive(Debug)]
1350 crate struct RustCodeBlock {
1351     /// The range in the markdown that the code block occupies. Note that this includes the fences
1352     /// for fenced code blocks.
1353     crate range: Range<usize>,
1354     /// The range in the markdown that the code within the code block occupies.
1355     crate code: Range<usize>,
1356     crate is_fenced: bool,
1357     crate lang_string: LangString,
1358 }
1359
1360 /// Returns a range of bytes for each code block in the markdown that is tagged as `rust` or
1361 /// untagged (and assumed to be rust).
1362 crate fn rust_code_blocks(md: &str, extra_info: &ExtraInfo<'_>) -> Vec<RustCodeBlock> {
1363     let mut code_blocks = vec![];
1364
1365     if md.is_empty() {
1366         return code_blocks;
1367     }
1368
1369     let mut p = Parser::new_ext(md, main_body_opts()).into_offset_iter();
1370
1371     while let Some((event, offset)) = p.next() {
1372         if let Event::Start(Tag::CodeBlock(syntax)) = event {
1373             let (lang_string, code_start, code_end, range, is_fenced) = match syntax {
1374                 CodeBlockKind::Fenced(syntax) => {
1375                     let syntax = syntax.as_ref();
1376                     let lang_string = if syntax.is_empty() {
1377                         Default::default()
1378                     } else {
1379                         LangString::parse(&*syntax, ErrorCodes::Yes, false, Some(extra_info))
1380                     };
1381                     if !lang_string.rust {
1382                         continue;
1383                     }
1384                     let (code_start, mut code_end) = match p.next() {
1385                         Some((Event::Text(_), offset)) => (offset.start, offset.end),
1386                         Some((_, sub_offset)) => {
1387                             let code = Range { start: sub_offset.start, end: sub_offset.start };
1388                             code_blocks.push(RustCodeBlock {
1389                                 is_fenced: true,
1390                                 range: offset,
1391                                 code,
1392                                 lang_string,
1393                             });
1394                             continue;
1395                         }
1396                         None => {
1397                             let code = Range { start: offset.end, end: offset.end };
1398                             code_blocks.push(RustCodeBlock {
1399                                 is_fenced: true,
1400                                 range: offset,
1401                                 code,
1402                                 lang_string,
1403                             });
1404                             continue;
1405                         }
1406                     };
1407                     while let Some((Event::Text(_), offset)) = p.next() {
1408                         code_end = offset.end;
1409                     }
1410                     (lang_string, code_start, code_end, offset, true)
1411                 }
1412                 CodeBlockKind::Indented => {
1413                     // The ending of the offset goes too far sometime so we reduce it by one in
1414                     // these cases.
1415                     if offset.end > offset.start && md.get(offset.end..=offset.end) == Some(&"\n") {
1416                         (
1417                             LangString::default(),
1418                             offset.start,
1419                             offset.end,
1420                             Range { start: offset.start, end: offset.end - 1 },
1421                             false,
1422                         )
1423                     } else {
1424                         (LangString::default(), offset.start, offset.end, offset, false)
1425                     }
1426                 }
1427             };
1428
1429             code_blocks.push(RustCodeBlock {
1430                 is_fenced,
1431                 range,
1432                 code: Range { start: code_start, end: code_end },
1433                 lang_string,
1434             });
1435         }
1436     }
1437
1438     code_blocks
1439 }
1440
1441 #[derive(Clone, Default, Debug)]
1442 pub struct IdMap {
1443     map: FxHashMap<String, usize>,
1444 }
1445
1446 fn init_id_map() -> FxHashMap<String, usize> {
1447     let mut map = FxHashMap::default();
1448     // This is the list of IDs used in Javascript.
1449     map.insert("help".to_owned(), 1);
1450     // This is the list of IDs used in HTML generated in Rust (including the ones
1451     // used in tera template files).
1452     map.insert("mainThemeStyle".to_owned(), 1);
1453     map.insert("themeStyle".to_owned(), 1);
1454     map.insert("theme-picker".to_owned(), 1);
1455     map.insert("theme-choices".to_owned(), 1);
1456     map.insert("settings-menu".to_owned(), 1);
1457     map.insert("help-button".to_owned(), 1);
1458     map.insert("main".to_owned(), 1);
1459     map.insert("search".to_owned(), 1);
1460     map.insert("crate-search".to_owned(), 1);
1461     map.insert("render-detail".to_owned(), 1);
1462     map.insert("toggle-all-docs".to_owned(), 1);
1463     map.insert("all-types".to_owned(), 1);
1464     map.insert("default-settings".to_owned(), 1);
1465     map.insert("rustdoc-vars".to_owned(), 1);
1466     map.insert("sidebar-vars".to_owned(), 1);
1467     map.insert("copy-path".to_owned(), 1);
1468     map.insert("TOC".to_owned(), 1);
1469     // This is the list of IDs used by rustdoc sections (but still generated by
1470     // rustdoc).
1471     map.insert("fields".to_owned(), 1);
1472     map.insert("variants".to_owned(), 1);
1473     map.insert("implementors-list".to_owned(), 1);
1474     map.insert("synthetic-implementors-list".to_owned(), 1);
1475     map.insert("foreign-impls".to_owned(), 1);
1476     map.insert("implementations".to_owned(), 1);
1477     map.insert("trait-implementations".to_owned(), 1);
1478     map.insert("synthetic-implementations".to_owned(), 1);
1479     map.insert("blanket-implementations".to_owned(), 1);
1480     map.insert("associated-types".to_owned(), 1);
1481     map.insert("associated-const".to_owned(), 1);
1482     map.insert("required-methods".to_owned(), 1);
1483     map.insert("provided-methods".to_owned(), 1);
1484     map.insert("implementors".to_owned(), 1);
1485     map.insert("synthetic-implementors".to_owned(), 1);
1486     map.insert("trait-implementations-list".to_owned(), 1);
1487     map.insert("synthetic-implementations-list".to_owned(), 1);
1488     map.insert("blanket-implementations-list".to_owned(), 1);
1489     map.insert("deref-methods".to_owned(), 1);
1490     map
1491 }
1492
1493 impl IdMap {
1494     pub fn new() -> Self {
1495         IdMap { map: init_id_map() }
1496     }
1497
1498     crate fn derive<S: AsRef<str> + ToString>(&mut self, candidate: S) -> String {
1499         let id = match self.map.get_mut(candidate.as_ref()) {
1500             None => candidate.to_string(),
1501             Some(a) => {
1502                 let id = format!("{}-{}", candidate.as_ref(), *a);
1503                 *a += 1;
1504                 id
1505             }
1506         };
1507
1508         self.map.insert(id.clone(), 1);
1509         id
1510     }
1511 }