note-tagger/README.md

Note Tagging & SEO Automation

Automatically tag your Obsidian notes, add slugs, and add SEO metadata using a local LLM.

The script requires these frontmatter fields:

• title (used as the basis for the SEO title)
• tags
• seo-title
• seo-description
• seo-keywords
• slug

Note: The script sends only the first 20,000 characters of the note to the LLM. This should be more than sufficient for most notes, however if you have extremely long notes then you can increase this by editing the CONTENT_CHAR_LIMIT constant in tag-notes.py.

Setup

1. Install dependencies:

   pip install pyyaml ruamel.yaml requests
   

2. Make sure LM Studio is running on with the preferred model loaded
3. Place these files in a directory:
   • tag-notes.py (the main script)
   • tag-taxonomy.yaml (your tag taxonomy)
4. Adjust Variables in 'tag-notes.py'
   • Edit the 'NOTES_FOLDER' variable to change the folder it searches
   • Edit the 'MODEL_NAME' variable to change the LLM model
   • Edit the 'LM_STUDIO_URL' variable to change URL of the LLM API
5. Adjust preset tags
   • Edit the tag-taxonomy.yaml file to change what tags you want it to use.

Usage

Simply run the script:

./tag-notes.py

It will recursively process all markdown files under NOTES_FOLDER.

What it does

The script will:

• ✓ Add tags (1-5) using your taxonomy + 1-2 new suggestions
• ✓ Add SEO title in the format {title}: {short descriptor}, built from the note's title: frontmatter field
• ✓ Add SEO description (strictly 150-160 chars, factual — re-asks the LLM once if the first response is out of range)
• ✓ Add SEO keywords (generous, 10-15 keywords)
• ✓ Add slug derived from the filename (lowercased, punctuation stripped, spaces/hyphens collapsed)
• ✓ Only updates empty fields - preserves existing values
• ✓ Updates files directly (no confirmation needed)
• ✓ Preserves existing frontmatter formatting via round-trip YAML

At the end of a run, if the LLM proposed any genuinely new tags, the script lists them and prompts you to append them to tag-taxonomy.yaml automatically.

Managing the taxonomy

At the end of each run, the script will prompt you to add any newly suggested tags to tag-taxonomy.yaml automatically. You can also edit the file by hand at any time.

The LLM will:

• Prefer existing taxonomy tags
• Suggest 1-2 new tags if the content warrants it
• Be conservative with new tag suggestions

Example output

Processing: /path/to/note.md
  + Added tags: self-hosting, linux, docker
    (New suggestions: containers)
  + Added SEO title: Setting Up a Self-Hosted Development Environment
  + Added SEO description
  + Added 12 SEO keywords
  ✓ Updated successfully

Troubleshooting

LLM connection errors:

• Check that LM Studio is running: curl http://localhost:1234/v1/models
• Verify the model is loaded in LM Studio

No frontmatter found:

• The note needs YAML frontmatter between --- delimiters

Fields already populated:

• Script skips notes where all four fields are already filled
• To re-process a note, clear the specific fields you want regenerated