Add --add-titles option

When this option is enabled, each parsed note will be considered to
start with a heading:

  # Title-of-note

even when no such line is present in the source file. The title is
inferred based on the filename of the note.

This option makes heavily nested note embeds make more sense in the
exported document, since it shows which note the embedded content comes
from. It loosely matches the behaviour of the mainline Obsidian UI when
viewing notes in preview mode.

Author: jforberg

src/lib.rs

@@ -230,6 +230,7 @@ pub struct Exporter<'a> {
     vault_contents: Option<Vec<PathBuf>>,
     walk_options: WalkOptions<'a>,
     process_embeds_recursively: bool,
+    add_titles: bool,
     postprocessors: Vec<&'a Postprocessor>,
     embed_postprocessors: Vec<&'a Postprocessor>,
 }
@@ -246,6 +247,7 @@ impl<'a> fmt::Debug for Exporter<'a> {
                 "process_embeds_recursively",
                 &self.process_embeds_recursively,
             )
+            .field("add_titles", &self.add_titles)
             .field(
                 "postprocessors",
                 &format!("<{} postprocessors active>", self.postprocessors.len()),
@@ -272,6 +274,7 @@ impl<'a> Exporter<'a> {
             frontmatter_strategy: FrontmatterStrategy::Auto,
             walk_options: WalkOptions::default(),
             process_embeds_recursively: true,
+            add_titles: false,
             vault_contents: None,
             postprocessors: vec![],
             embed_postprocessors: vec![],
@@ -312,6 +315,23 @@ impl<'a> Exporter<'a> {
         self
     }
 
+    /// Enable or disable addition of title headings to the top of each parsed note
+    ///
+    /// When this option is enabled, each parsed note will be considered to start with a heading:
+    ///
+    ///   # Title-of-note
+    ///
+    /// even when no such line is present in the source file. The title is inferred based on the
+    /// filename of the note.
+    ///
+    /// This option makes heavily nested note embeds make more sense in the exported document,
+    /// since it shows which note the embedded content comes from. It loosely matches the behaviour
+    /// of the mainline Obsidian UI when viewing notes in preview mode.
+    pub fn add_titles(&mut self, add_titles: bool) -> &mut Exporter<'a> {
+        self.add_titles = add_titles;
+        self
+    }
+
     /// Append a function to the chain of [postprocessors][Postprocessor] to run on exported Obsidian Markdown notes.
     pub fn add_postprocessor(&mut self, processor: &'a Postprocessor) -> &mut Exporter<'a> {
         self.postprocessors.push(processor);
@@ -455,6 +475,16 @@ impl<'a> Exporter<'a> {
         // Most of the time, a reference triggers 5 events: [ or ![, [, <text>, ], ]
         let mut buffer = Vec::with_capacity(5);
 
+        if self.add_titles {
+            // Ensure that each (possibly embedded) note starts with a reasonable top-level heading
+            let note_name = infer_note_title_from_path(path);
+            let h1_tag = Tag::Heading(HeadingLevel::H1, None, vec![]);
+
+            events.push(Event::Start(h1_tag.clone()));
+            events.push(Event::Text(note_name));
+            events.push(Event::End(h1_tag.clone()));
+        }
+
         for event in Parser::new_ext(&content, parser_options) {
             if ref_parser.state == RefParserState::Resetting {
                 events.append(&mut buffer);
@@ -725,6 +755,15 @@ fn lookup_filename_in_vault<'a>(
     })
 }
 
+fn infer_note_title_from_path<'a>(path: &'a Path) -> CowStr<'a> {
+    const PLACEHOLDER_TITLE: &str = "invalid-note-title";
+
+    match path.file_stem() {
+        None => CowStr::from(PLACEHOLDER_TITLE),
+        Some(s) => CowStr::from(s.to_string_lossy().into_owned()),
+    }
+}
+
 fn render_mdevents_to_mdtext(markdown: MarkdownEvents) -> String {
     let mut buffer = String::new();
     cmark_with_options(

src/main.rs

@@ -54,6 +54,13 @@ struct Opts {
         default = "false"
     )]
     hard_linebreaks: bool,
+
+    #[options(
+        no_short,
+        help = "Add a heading to the beginning of each note based on its filename",
+        default = "false"
+    )]
+    add_titles: bool,
 }
 
 fn frontmatter_strategy_from_str(input: &str) -> Result<FrontmatterStrategy> {
@@ -88,6 +95,7 @@ fn main() {
     let mut exporter = Exporter::new(root, destination);
     exporter.frontmatter_strategy(args.frontmatter_strategy);
     exporter.process_embeds_recursively(!args.no_recursive_embeds);
+    exporter.add_titles(args.add_titles);
     exporter.walk_options(walk_options);
 
     if args.hard_linebreaks {

tests/export_test.rs

@@ -363,6 +363,25 @@ fn test_no_recursive_embeds() {
     );
 }
 
+#[test]
+fn test_add_titles() {
+    let tmp_dir = TempDir::new().expect("failed to make tempdir");
+
+    let mut exporter = Exporter::new(
+        // Github bug #26 causes embeds not to work with single-file exports. As a workaround, we
+        // export a whole directory in this test.
+        PathBuf::from("tests/testdata/input/add-titles/"),
+        tmp_dir.path().to_path_buf(),
+    );
+    exporter.add_titles(true);
+    exporter.run().expect("exporter returned error");
+
+    assert_eq!(
+        read_to_string("tests/testdata/expected/add-titles/Main note.md").unwrap(),
+        read_to_string(tmp_dir.path().clone().join(PathBuf::from("Main note.md"))).unwrap(),
+    );
+}
+
 #[test]
 fn test_non_ascii_filenames() {
     let tmp_dir = TempDir::new().expect("failed to make tempdir");

tests/testdata/expected/add-titles/Main note.md

@@ -0,0 +1,7 @@
+# Main note
+
+# Sub note
+
+# Sub sub note
+
+No more notes

tests/testdata/input/add-titles/Main note.md

@@ -0,0 +1 @@
+![[Sub note]]

tests/testdata/input/add-titles/Sub note.md

@@ -0,0 +1 @@
+![[Sub sub note]]

tests/testdata/input/add-titles/Sub sub note.md

@@ -0,0 +1 @@
+No more notes