Add option to include a table of contents in each gist, defaulting to disabled (#726)

* Add option to include a table of contents in each gist, defaulting to disabled

Built entirely with GitHub Copilot Agent Mode in VS Code ❤️🤖

Closes #709.

* Update readme with new option

* Add headline about tables of contents

* Tweak readme headline

* Switch to remark-toc and tweak option name and description

Author: timrogers

README.md

@@ -6,6 +6,7 @@ This plugin for Obsidian (https://obsidian.md) allows you to share your notes as
 - 💼 Works with GitHub.com and [GitHub Enterprise Server](https://docs.github.com/en/enterprise-server/admin/overview/about-github-enterprise-server)
 - 🔄 Update your gist when you make changes to your notes
 - 🗑️ Delete a gist if you change your mind
+- 📜 Optionally include a table of contents in your gist for easy navigation
 
 ## Usage
 
@@ -48,6 +49,7 @@ This plugin for Obsidian (https://obsidian.md) allows you to share your notes as
 - **Include front matter in gists** (_disabled by default_): Whether your gists should include frontmatter (properties). If this is disabled, the front matter will be stripped from your gists.
 - **Enable auto-saving Gists after edit** (_disabled by default_): Whether your gists should be automatically updated when you save your note. If this is disabled, you can update your gists automatically with the normal "share" command.
 - **Enable auto-save notice** (_disabled by default_): Whether a notice should be displayed when your gists are automatically updated. This option is only relevant if the "Enable auto-saving Gists after edit" option above is turned on.
+- **Include table of contents** (_disabled by default_): Whether to automatically generate and include a table of contents at the start of each gist
 
 ## Securing your GitHub personal access token(s)
 

main.ts

@@ -14,6 +14,8 @@ import {
   debounce,
 } from 'obsidian';
 import matter from 'gray-matter';
+import { remark } from 'remark';
+import remarkToc from 'remark-toc';
 import {
   CreateGistResultStatus,
   DeleteGistResultStatus,
@@ -45,13 +47,15 @@ interface ShareAsGistSettings {
   enableAutoSaving: boolean;
   showAutoSaveNotice: boolean;
   includeFrontMatter: boolean;
+  includeTableOfContents: boolean;
 }
 
 const DEFAULT_SETTINGS: ShareAsGistSettings = {
   includeFrontMatter: false,
   enableUpdatingGistsAfterCreation: true,
   enableAutoSaving: false,
   showAutoSaveNotice: false,
+  includeTableOfContents: false,
 };
 
 interface ShareGistEditorCallbackParams {
@@ -90,6 +94,11 @@ const getLatestSettings = async (
   return plugin.settings;
 };
 
+const addTableOfContents = async (content: string): Promise<string> => {
+  const resultAsVFile = await remark().use(remarkToc).process(content);
+  return String(resultAsVFile);
+};
+
 const stripFrontMatter = (content: string): string => matter(content).content;
 
 /*
@@ -209,8 +218,11 @@ const shareGistEditorCallback =
   (opts: ShareGistEditorCallbackParams) => async () => {
     const { isPublic, app, plugin, target } = opts;
 
-    const { enableUpdatingGistsAfterCreation, includeFrontMatter } =
-      await getLatestSettings(plugin);
+    const {
+      enableUpdatingGistsAfterCreation,
+      includeFrontMatter,
+      includeTableOfContents,
+    } = await getLatestSettings(plugin);
 
     const view = app.workspace.getActiveViewOfType(MarkdownView);
 
@@ -227,10 +239,14 @@ const shareGistEditorCallback =
       target,
     ).filter((sharedGist) => sharedGist.isPublic === isPublic);
 
-    const gistContent = includeFrontMatter
+    const baseContent = includeFrontMatter
       ? originalContent
       : stripFrontMatter(originalContent);
 
+    const content = includeTableOfContents
+      ? await addTableOfContents(baseContent)
+      : baseContent;
+
     if (enableUpdatingGistsAfterCreation && existingSharedGists.length) {
       new SelectExistingGistModal(
         app,
@@ -240,7 +256,7 @@ const shareGistEditorCallback =
           if (sharedGist) {
             const result = await updateGist({
               sharedGist,
-              content: gistContent,
+              content,
             });
 
             if (result.status === CreateGistResultStatus.Succeeded) {
@@ -260,7 +276,7 @@ const shareGistEditorCallback =
             new SetGistDescriptionModal(app, filename, async (description) => {
               const result = await createGist({
                 target,
-                content: gistContent,
+                content,
                 description,
                 filename,
                 isPublic,
@@ -287,7 +303,7 @@ const shareGistEditorCallback =
       new SetGistDescriptionModal(app, filename, async (description) => {
         const result = await createGist({
           target,
-          content: gistContent,
+          content,
           description,
           filename,
           isPublic,
@@ -320,18 +336,25 @@ const documentChangedAutoSaveCallback = async (
 ) => {
   const { plugin, file, content: rawContent } = opts;
 
-  const { includeFrontMatter, showAutoSaveNotice } =
+  const { includeFrontMatter, showAutoSaveNotice, includeTableOfContents } =
     await getLatestSettings(plugin);
 
   const existingSharedGists = getSharedGistsForFile(rawContent);
 
-  const content = includeFrontMatter
+  const baseContent = includeFrontMatter
     ? rawContent
     : stripFrontMatter(rawContent);
 
+  const content = includeTableOfContents
+    ? await addTableOfContents(baseContent)
+    : baseContent;
+
   if (existingSharedGists.length) {
     for (const sharedGist of existingSharedGists) {
-      const result = await updateGist({ sharedGist, content });
+      const result = await updateGist({
+        sharedGist,
+        content,
+      });
       if (result.status === CreateGistResultStatus.Succeeded) {
         const updatedContent = upsertSharedGistForFile(
           result.sharedGist,
@@ -757,5 +780,19 @@ class ShareAsGistSettingTab extends PluginSettingTab {
             await this.plugin.saveSettings();
           }),
       );
+
+    new Setting(containerEl)
+      .setName('Include table of contents')
+      .setDesc(
+        'Whether to automatically generate and include a table of contents in the shared gist. The table of contents will be inserted directly after the `Contents` or `Table of Contents` heading, if one exists.',
+      )
+      .addToggle((toggle) =>
+        toggle
+          .setValue(this.plugin.settings.includeTableOfContents)
+          .onChange(async (value) => {
+            this.plugin.settings.includeTableOfContents = value;
+            await this.plugin.saveSettings();
+          }),
+      );
   }
 }