Document tag normalization rules

README.md

@@ -15,9 +15,16 @@ It integrates with your Instapaper account and allows you to:
 2. Enable the installed "Instapaper" plugin (**Settings → Community plugins → Installed plugins**).
 3. Click the "Options" icon (or go to **Settings → Instapaper**) to connect your Instapaper account, start syncing highlights, and manage other options.
 
+## Tags
+
+[Obsidian's tag format](https://help.obsidian.md/Editing+and+formatting/Tags#Tag+format) is more restrictive than Instapaper's so we apply some normalization rules:
+
+- Obsidian tags cannot contain spaces. We replace runs of one or more spaces with a hyphen (`-`).
+- Obsidian tags must contain a least one non-numeric character. We append an underscore (`_`) to any entirely numeric Instapaper tag.
+
 ## Feedback
 
-Please send general feedback to: [email protected]
+Please send general feedback to: <[email protected]>
 
 [Code contributions](CONTRIBUTING.md) for improvements are also welcome.
 

src/notes.ts

@@ -58,7 +58,7 @@ export async function syncNotes(
                 frontmatter['url'] = article.url;
                 frontmatter['date'] = formatTimestamp(article.time);
                 frontmatter['tags'] = (article.tags.length > 0)
-                    ? article.tags.map(formatTag) : undefined;
+                    ? article.tags.map(normalizeTag) : undefined;
                 if (article.pubtime) {
                     frontmatter['pubdate'] = formatTimestamp(article.pubtime);
                 }
@@ -112,7 +112,7 @@ function contentForHighlight(highlight: InstapaperHighlight): string {
     return content;
 }
 
-function formatTag(tag: InstapaperTag): string {
+function normalizeTag(tag: InstapaperTag): string {
     // Obsidian tags cannot contain spaces.
     let name = tag.name.trim().replace(/\s+/, '-');