1#![deny(missing_docs)]
28
29mod abbr_budget;
30pub mod accessibility;
32pub mod ast;
33pub mod ast_envelope;
34mod ast_fingerprint;
35pub mod ast_json;
36pub mod ast_merge;
37pub mod ast_patch;
38pub mod ast_sidecars;
39pub mod bbcode_migrate;
40mod carrier_markers;
41mod citations;
42pub mod conversion_diagnostics;
43pub mod djot_migrate;
44mod document_ids;
45mod escape;
46mod extension;
47pub mod extensions;
48pub mod html_import;
49mod include_walk;
50pub mod includes;
52pub mod incremental;
54mod index_budget;
55mod inline_carriers;
56pub mod lint;
57mod markdown_assessment;
58#[doc(hidden)]
59pub use markdown_assessment::take_attribute_opener_scan_bytes;
60mod markdown_gfm_autolinks;
61mod markdown_github_alerts;
62pub mod markdown_import;
63mod markdown_strike;
64pub mod migration;
66mod parse;
67pub mod profile;
68pub mod profile_filter;
69pub mod prosemirror;
70mod render;
71mod render_ansi;
72mod render_carve;
73mod render_carve_error;
74#[path = "render/render_depth.rs"]
75mod render_depth;
76#[path = "render/render_loss.rs"]
77mod render_loss;
78mod render_markdown;
79mod render_plain;
80#[path = "render/render_text.rs"]
81mod render_text;
82mod roundtrip;
83mod sentinel_run;
84#[path = "source/source_layout.rs"]
85mod source_layout;
86#[path = "source/source_patch.rs"]
87mod source_patch;
88#[path = "source/source_positions.rs"]
89mod source_positions;
90mod stamp;
91pub mod stream;
93#[path = "table/table_display_width.rs"]
94mod table_display_width;
95#[path = "table/table_source_metadata.rs"]
96mod table_source_metadata;
97#[path = "table/table_spans.rs"]
98mod table_spans;
99mod table_unicode_18_data;
100#[path = "table/table_width.rs"]
101mod table_width;
102mod translit_map;
103mod wire_fields;
104
105pub(crate) const NBSP_PLACEHOLDER: char = '\0';
109pub const SPEC_VERSION: &str = "0.1";
120
121pub use accessibility::{lint_accessibility, AccessibilityDiagnostic, AccessibilitySeverity};
122pub use ast::*;
123pub use ast_envelope::{
124 from_ast_envelope_json, to_ast_envelope_json, AstEnvelopeError, AstEnvelopeExtension,
125 AstEnvelopeOptions, AstEnvelopeReaderOptions, AST_CONTRACT_VERSION, CORE_AST_VOCABULARY,
126};
127pub use ast_json::{from_json, to_json, try_to_json, AstJsonError, AstJsonErrorKind};
128pub use ast_merge::{
129 merge_ast, merge_ast_with_resolver, MergeConflict, MergeConflictReason, MergeResolution,
130 MergeResult,
131};
132pub use ast_patch::{
133 apply_ast_patch, apply_reversible_ast_patch, ast_patch_from_json, ast_patch_to_json,
134 create_ast_patch, create_reversible_ast_patch, AstPatchError, AstPatchOperation,
135 ReversibleAstPatch,
136};
137pub use ast_sidecars::{
138 authored_provenance, fresh_node_identity, from_annotation_ranges_json, from_node_identity_json,
139 from_provenance_json, parse_with_authored_provenance, to_annotation_ranges_json,
140 to_node_identity_json, to_provenance_json, AnnotationAnchor, AnnotationRange, AnnotationRanges,
141 AstSidecarError, NodeIdentity, NodeIdentityEntry, NodeProvenance, Provenance, ProvenanceOrigin,
142 ProvenanceSource,
143};
144pub use bbcode_migrate::{bbcode_to_carve, BbcodeImportError, BBCODE_MAX_INPUT_LENGTH};
145pub use citations::{
146 parse_locator, CitationMode, Citations, CslDate, CslEntry, CslName, ParsedLocator,
147};
148pub use conversion_diagnostics::{
149 conversion_diagnostics, to_conversion_diagnostics_json, ConversionDiagnostic,
150 ConversionDiagnosticCode, ConversionDiagnostics, ConversionPos,
151 DEFAULT_MAX_CONVERSION_DIAGNOSTICS,
152};
153pub use djot_migrate::djot_to_carve;
154pub use extension::{
155 label_default, AsciiHeadingIds, BeforeRenderContext, BlockMatch, CarveExtension, InlineMatch,
156 MatcherContext, Mode, Options, RenderContext, SmartTypographyMode, SocialLinkKind,
157 SocialLinkResolver, SocialLinkResolverInput, StaticRenderers, LABEL_FOOTNOTE_BACKLINK,
158};
159pub use extensions::{
160 sanitize_svg, Autolink, AutolinkOptions, CodeCallouts, CodeGroup, CodeGroupOptions,
161 ColorSwatch, ContentMode, CrossrefStyle, Details, ExternalLinks, ExternalLinksOptions,
162 FencedRender, FencedRenderOptions, Glossary, HeadingLevelShift, HeadingLevelShiftOptions,
163 HeadingNumbers, HeadingNumbersOptions, HeadingPermalinks, HeadingPermalinksOptions,
164 HeadingReference, HeadingReferenceOptions, ImgFence, Index, ListTable, ListType, MathBlock,
165 MathBlockOptions, Position, QuoteCharacters, SanitizeResult, SanitizeSvgOptions, SmartQuotes,
166 Spoiler, SwatchPosition, SwatchShape, TabNormalize, TableOfContents, TableOfContentsOptions,
167 Tabs, TabsMode, TabsOptions, TocPlacement, UrlGenerator, Wikilinks, WikilinksOptions,
168 SMART_QUOTE_LOCALES,
169};
170pub use html_import::{
171 html_to_ast, html_to_carve, HtmlImportAdapter, HtmlImportDiagnostic, HtmlImportDiagnosticCode,
172 HtmlImportError, HtmlImportMode, HtmlImportOptions, HtmlImportReport, HtmlImportResult,
173 HtmlImportSeverity, ImportConfidence, ImportFidelity, MAX_HTML_IMPORT_DEPTH,
174};
175pub use includes::{
176 expand_includes, expands_for_target, select_include_region, IncludeContext, IncludeDenial,
177 IncludeDependency, IncludeOptions, IncludeRegion, IncludeRegionError, IncludeRegionMode,
178 IncludeResolved, IncludeResolver, IncludeResult, IncludeWarning, DEFAULT_MAX_DEPTH,
179 DEFAULT_MAX_RESOLVER_CALLS, DEFAULT_MAX_WARNINGS,
180};
181#[cfg(feature = "fs")]
182pub use includes::{FileSystemResolver, DEFAULT_MAX_FILE_BYTES};
183pub use incremental::{
184 parse_snapshot, parse_snapshot_with_identity, reparse, IncrementalParse, IncrementalParseError,
185 ParserSnapshot, TextChange,
186};
187pub use lint::{lint_carve, lint_carve_with_options, migrate_case_only_references, LintWarning};
188pub use markdown_import::{
189 markdown_to_ast, markdown_to_carve, migration_raw_heading_ids, try_markdown_to_ast,
190 try_markdown_to_carve,
191};
192pub use migration::{
193 fragment_fixup_diagnostic, migrate_bbcode, migrate_djot, migrate_html, migrate_markdown,
194 try_migrate_markdown, try_migrate_markdown_for_directory,
195 try_migrate_markdown_for_directory_with_destinations, MigrationConfidence, MigrationDiagnostic,
196 MigrationFidelity, MigrationReport, MigrationResult, SourceFormat,
197};
198#[cfg(feature = "experimental-event-parser")]
199pub use parse::parse_experimental_event_blocks;
200#[cfg(feature = "experimental-event-parser-options")]
201pub use parse::parse_experimental_event_blocks_with_options;
202pub use parse::{decision_trace, parse, parse_with_options};
203pub use profile::{DisallowedAction, LinkPolicy, Profile, ProfileViolation, ProfileViolationError};
204pub use profile_filter::{apply_profile, apply_profile_with_typography, ProfileFilterResult};
205pub use prosemirror::{
206 from_prosemirror, from_prosemirror_with_report, to_prosemirror, ProseMirrorDoc,
207 ProseMirrorError, ProseMirrorImport,
208};
209pub use render::{
210 render_html, render_html_owned, render_html_owned_with_options, render_html_with_options,
211 MAX_RENDER_DEPTH,
212};
213pub use render_ansi::{render_ansi, render_ansi_with_options};
214pub use render_carve::{render_carve, render_carve_with_options, CarveWriterOptions};
215pub use render_carve_error::{CarveWriteError, RenderCarveError, SourceUnspellable};
216pub use render_depth::RenderDepthError;
217pub use render_loss::{
218 with_render_loss_report, CheckedRenderOptions, RawNodeType, RenderLoss, RenderLossError,
219 RenderResult, RenderTarget, DEFAULT_MAX_RENDER_LOSSES,
220};
221pub use render_markdown::{render_markdown, render_markdown_with_options, MarkdownRenderError};
222pub use render_plain::{render_plain_text, render_plain_text_with_options};
223pub use source_layout::{parse_with_source_layout, to_source_layout_json};
224pub use source_patch::{
225 apply_source_patch, create_source_patch, source_fingerprint, SourceEdit, SourceEditKind,
226 SourcePatch, SourcePatchError, SourceSuggestion,
227};
228pub use stamp::{needs_review, read_stamp, stamp_carve, Stamp, StampForm};
229pub use stream::{try_render_html_streaming, StreamOutcome};
230
231pub fn to_html(source: &str) -> String {
237 let options = Options::default();
238 if let Some(html) = parse::try_layout_html(source, &options) {
239 return html;
240 }
241 let (doc, crossref_index) = parse::parse_with_render_index(source, &options);
242 render::render_html_owned_with_index(
243 doc,
244 &options,
245 crossref_index,
246 source.contains("[@") || source.contains(":::"),
247 source.contains("[^") || source.contains("^["),
248 )
249 .expect("the parse cap sits below the render ceiling, so a parsed tree never reaches it")
250}
251
252pub fn to_markdown(source: &str) -> String {
263 render_markdown(&parse_with_options(
264 source,
265 &Options::default().with_positions(true),
266 ))
267 .expect("the parse cap sits below the render ceiling, so a parsed tree never reaches it")
268}
269
270pub fn to_plain_text(source: &str) -> String {
281 render_plain_text(&parse_with_options(
282 source,
283 &Options::default().with_positions(true),
284 ))
285 .expect("the parse cap sits below the render ceiling, so a parsed tree never reaches it")
286}
287
288pub fn to_ansi(source: &str) -> String {
299 render_ansi(&parse_with_options(
300 source,
301 &Options::default().with_positions(true),
302 ))
303 .expect("the parse cap sits below the render ceiling, so a parsed tree never reaches it")
304}
305
306pub fn to_carve(source: &str) -> String {
320 try_to_carve_with_options(source, &Options::default()).unwrap_or_else(|_| source.to_string())
321}
322
323pub fn to_carve_patch(source: &str) -> SourcePatch {
325 let formatted = to_carve(source);
326 let mut patch = create_source_patch(
327 source,
328 &formatted,
329 SourceEditKind::Formatting,
330 "canonical-format",
331 );
332 if !patch.edits.is_empty() && lint::lint_with_recovery(source, &Options::default()).1 {
333 patch.edits.clear();
334 patch.unresolved.push(SourceSuggestion {
335 start: 0,
336 end: patch.source_bytes,
337 replacement: formatted,
338 kind: SourceEditKind::Formatting,
339 code: "invalid-container-metadata".into(),
340 message:
341 "Canonical formatting drops invalid container metadata; review the proposed source."
342 .into(),
343 });
344 }
345 patch
346}
347
348pub fn to_html_with_report(
350 source: &str,
351 checked_options: CheckedRenderOptions,
352) -> Result<RenderResult<String>, RenderLossError> {
353 render_loss::checked(RenderTarget::Html, checked_options, || {
354 render_html_owned(parse_with_options(
355 source,
356 &Options::default().with_positions(true),
357 ))
358 .expect("the parse cap sits below the render ceiling")
359 })
360}
361
362pub fn to_html_with_options_and_report(
372 source: &str,
373 options: &Options<'_>,
374 checked_options: CheckedRenderOptions,
375) -> Result<RenderResult<String>, RenderLossError> {
376 render_loss::checked(RenderTarget::Html, checked_options, || {
377 to_html_with_options(source, options)
378 })
379}
380
381pub fn to_markdown_with_report(
383 source: &str,
384 checked_options: CheckedRenderOptions,
385) -> Result<RenderResult<String>, RenderLossError> {
386 render_loss::checked(RenderTarget::Markdown, checked_options, || {
387 let (doc, unattached) = parse::collecting_unattached_block_attrs(|| {
388 parse_with_options(source, &Options::default().with_positions(true))
389 });
390 let rendered = render_markdown(&doc).expect("the parse cap sits below the render ceiling");
391 render_loss::collect_markdown_unattached(unattached);
392 rendered
393 })
394}
395
396pub fn to_plain_text_with_report(
398 source: &str,
399 checked_options: CheckedRenderOptions,
400) -> Result<RenderResult<String>, RenderLossError> {
401 render_loss::checked(RenderTarget::Plain, checked_options, || {
402 render_plain_text(&parse_with_options(
403 source,
404 &Options::default().with_positions(true),
405 ))
406 .expect("the parse cap sits below the render ceiling")
407 })
408}
409
410pub fn to_ansi_with_report(
413 source: &str,
414 checked_options: CheckedRenderOptions,
415) -> Result<RenderResult<String>, RenderLossError> {
416 render_loss::checked(RenderTarget::Ansi, checked_options, || {
417 render_ansi(&parse_with_options(
418 source,
419 &Options::default().with_positions(true),
420 ))
421 .expect("the parse cap sits below the render ceiling")
422 })
423}
424
425pub fn to_carve_with_report(
427 source: &str,
428 checked_options: CheckedRenderOptions,
429) -> Result<RenderResult<String>, RenderLossError> {
430 render_loss::checked(RenderTarget::Carve, checked_options, || to_carve(source))
431}
432
433pub fn try_to_carve_with_options(
451 source: &str,
452 options: &Options<'_>,
453) -> Result<String, CarveWriteError> {
454 if let Some(profile) = &options.profile {
459 let max_length = profile.max_length();
460 if max_length > 0 && source.len() > max_length {
461 return Err(CarveWriteError::Profile(ProfileViolationError {
462 violations: vec![ProfileViolation {
463 node_type: "document".to_string(),
464 reason: "max_length_exceeded".to_string(),
465 reason_description: Some(format!(
466 "Input exceeds the profile's maximum length of {max_length} bytes ({} given).",
467 source.len()
468 )),
469 }],
470 }));
471 }
472 }
473 let normalized = parse::normalize_source(source);
483 let source = normalized.as_ref();
484 let (mut frontmatter, _) = raw_frontmatter(source);
485 let mut doc = parse::parse_for_carve(source);
486 if frontmatter.is_some() {
487 doc.frontmatter.clear();
488 doc.frontmatter_raw = None;
489 }
490 if let Some(profile) = &options.profile {
491 let base_host = options.profile_base_host.as_deref();
492 doc = apply_profile_with_typography(doc, profile, base_host, options.smart_typography)?.doc;
493 if frontmatter.is_some() && !profile.is_type_allowed_on("frontmatter", true) {
499 frontmatter = None;
500 }
501 }
502 let rendered = render_carve_with_options(
508 &doc,
509 &CarveWriterOptions::default().with_align_tables(options.align_tables),
510 )?;
511 let body = if rendered.ends_with('\n') {
522 rendered
523 } else {
524 format!("{rendered}\n")
525 };
526 Ok(match frontmatter {
527 Some(frontmatter) if body.trim().is_empty() => format!("{frontmatter}\n"),
528 Some(frontmatter) => format!("{frontmatter}\n\n{body}"),
529 None => body,
530 })
531}
532
533fn raw_frontmatter(source: &str) -> (Option<String>, &str) {
534 let Some((kind, rest_start, content_len, after)) = parse::frontmatter_extent(source) else {
539 return (None, source);
540 };
541 let rest = &source[rest_start..];
542 let open = format!(
555 "---{}",
556 if kind.is_empty() {
557 parse::DEFAULT_FRONTMATTER_FORMAT
558 } else {
559 kind
560 }
561 );
562 let content = &rest[..content_len];
563 let content = if content_len == after {
566 content.trim_end_matches('\n')
567 } else {
568 content
569 };
570 let body = &rest[after..];
571 (Some(format!("{open}\n{content}\n---")), body)
572}
573
574fn prepare_doc(
584 source: &str,
585 options: &Options<'_>,
586 effective_mode: Mode,
587 target_is_html: bool,
588) -> Result<ast::Document, ProfileViolationError> {
589 let Some(profile) = &options.profile else {
590 return Ok(parsed_doc_with_hooks(
591 source,
592 options,
593 effective_mode,
594 target_is_html,
595 ));
596 };
597 let max_length = profile.max_length();
598 if max_length > 0 && source.len() > max_length {
599 let violation = ProfileViolation {
602 node_type: "document".to_string(),
603 reason: "max_length_exceeded".to_string(),
604 reason_description: Some(format!(
605 "Input exceeds the profile's maximum length of {max_length} bytes ({} given).",
606 source.len()
607 )),
608 };
609 return Err(ProfileViolationError {
610 violations: vec![violation],
611 });
612 }
613 let doc = parsed_doc_with_hooks(source, options, effective_mode, target_is_html);
614 let base_host = options.profile_base_host.as_deref();
615 Ok(apply_profile_with_typography(doc, profile, base_host, options.smart_typography)?.doc)
616}
617
618pub fn prepare_document_for_render(
622 mut doc: ast::Document,
623 options: &Options<'_>,
624 effective_mode: Mode,
625 target_is_html: bool,
626) -> Result<ast::Document, ProfileViolationError> {
627 if let Some(profile) = &options.profile {
638 let max_length = profile.max_length();
648 let input_len = doc.untrusted_input_len();
649 if max_length > 0 && input_len > max_length {
650 let violation = ProfileViolation {
651 node_type: "document".to_string(),
652 reason: "max_length_exceeded".to_string(),
653 reason_description: Some(format!(
654 "Input exceeds the profile's maximum length of {max_length} bytes ({input_len} given)."
655 )),
656 };
657 return Err(ProfileViolationError {
658 violations: vec![violation],
659 });
660 }
661 }
662
663 let ctx = extension::BeforeRenderContext::new(options, effective_mode, target_is_html);
664 for ext in &options.extensions {
665 doc = ext.before_render(doc, &ctx);
666 }
667 let Some(profile) = &options.profile else {
668 return Ok(doc);
669 };
670 let base_host = options.profile_base_host.as_deref();
671 Ok(apply_profile_with_typography(doc, profile, base_host, options.smart_typography)?.doc)
672}
673
674pub fn try_to_html_with_options(
678 source: &str,
679 options: &Options<'_>,
680) -> Result<String, ProfileViolationError> {
681 Ok(
683 render_html_owned_with_options(prepare_doc(source, options, options.mode, true)?, options)
684 .expect(
685 "the parse cap sits below the render ceiling, so a parsed tree never reaches it",
686 ),
687 )
688}
689
690pub fn try_to_json_with_options(
692 source: &str,
693 options: &Options<'_>,
694) -> Result<String, ProfileViolationError> {
695 Ok(to_json(&prepare_doc(
696 source,
697 options,
698 Mode::Interactive,
699 false,
700 )?))
701}
702
703pub fn to_json_with_options(source: &str, options: &Options<'_>) -> String {
707 try_to_json_with_options(source, options).unwrap_or_default()
708}
709
710pub fn try_to_markdown_with_options(
716 source: &str,
717 options: &Options<'_>,
718) -> Result<String, CarveWriteError> {
719 let (doc, unattached) = parse::collecting_unattached_block_attrs(|| {
720 prepare_doc(source, options, Mode::Interactive, false)
721 });
722 let rendered = render_markdown_with_options(&doc?, options)?;
723 render_loss::collect_markdown_unattached(unattached);
724 Ok(rendered)
725}
726
727pub fn try_to_plain_text_with_options(
731 source: &str,
732 options: &Options<'_>,
733) -> Result<String, ProfileViolationError> {
734 Ok(render_plain_text_with_options(
735 &prepare_doc(source, options, Mode::Interactive, false)?,
736 options,
737 )
738 .expect("the parse cap sits below the render ceiling, so a parsed tree never reaches it"))
739}
740
741pub fn try_to_ansi_with_options(
745 source: &str,
746 options: &Options<'_>,
747) -> Result<String, ProfileViolationError> {
748 Ok(render_ansi_with_options(
749 &prepare_doc(source, options, Mode::Interactive, false)?,
750 options,
751 )
752 .expect("the parse cap sits below the render ceiling, so a parsed tree never reaches it"))
753}
754
755fn parsed_doc_with_hooks(
760 source: &str,
761 options: &Options<'_>,
762 effective_mode: Mode,
763 target_is_html: bool,
764) -> ast::Document {
765 doc_with_hooks(
766 parse_with_options(source, options),
767 options,
768 effective_mode,
769 target_is_html,
770 )
771}
772
773fn doc_with_hooks(
774 mut doc: ast::Document,
775 options: &Options<'_>,
776 effective_mode: Mode,
777 target_is_html: bool,
778) -> ast::Document {
779 let ctx = extension::BeforeRenderContext::new(options, effective_mode, target_is_html);
780 for ext in &options.extensions {
781 doc = ext.before_render(doc, &ctx);
782 }
783 doc
784}
785
786pub fn prepare_doc_with_includes(
800 source: &str,
801 options: &Options<'_>,
802 include_options: &IncludeOptions<'_>,
803 effective_mode: Mode,
804 target_is_html: bool,
805) -> Result<PreparedWithIncludes, ProfileViolationError> {
806 if let Some(profile) = &options.profile {
807 let max_length = profile.max_length();
808 if max_length > 0 && source.len() > max_length {
809 return Err(ProfileViolationError {
810 violations: vec![ProfileViolation {
811 node_type: "document".to_string(),
812 reason: "max_length_exceeded".to_string(),
813 reason_description: Some(format!(
814 "Input exceeds the profile's maximum length of {max_length} bytes ({} given).",
815 source.len()
816 )),
817 }],
818 });
819 }
820 }
821 let expanded = includes::expand_includes_with_extensions(
822 parse_with_options(source, options),
823 source,
824 include_options,
825 &options.extensions,
826 );
827 let doc = doc_with_hooks(expanded.doc, options, effective_mode, target_is_html);
828 let doc = match &options.profile {
829 Some(profile) => apply_profile(doc, profile, options.profile_base_host.as_deref())?.doc,
830 None => doc,
831 };
832 Ok(PreparedWithIncludes {
833 doc,
834 warnings: expanded.warnings,
835 suppressed_warnings: expanded.suppressed_warnings,
836 dependencies: expanded.dependencies,
837 })
838}
839
840pub struct PreparedWithIncludes {
843 pub doc: ast::Document,
845 pub warnings: Vec<IncludeWarning>,
847 pub suppressed_warnings: usize,
849 pub dependencies: Vec<IncludeDependency>,
851}
852
853pub fn to_html_with_options(source: &str, options: &Options<'_>) -> String {
858 try_to_html_with_options(source, options).unwrap_or_default()
859}
860
861pub fn to_markdown_with_options(source: &str, options: &Options<'_>) -> String {
864 try_to_markdown_with_options(source, options).unwrap_or_default()
865}
866
867pub fn to_plain_text_with_options(source: &str, options: &Options<'_>) -> String {
869 try_to_plain_text_with_options(source, options).unwrap_or_default()
870}
871
872pub fn to_ansi_with_options(source: &str, options: &Options<'_>) -> String {
874 try_to_ansi_with_options(source, options).unwrap_or_default()
875}
876
877pub fn to_carve_with_options(source: &str, options: &Options<'_>) -> String {
880 try_to_carve_with_options(source, options).unwrap_or_default()
881}