Hugo to Nostr Publisher

The Hugo to Nostr Publisher project provides a robust solution for effortlessly publishing Hugo blog posts to the Nostr network as kind:30023 (Article) events. This tool not only allows users to track published posts but also enables management of deletions, making it an essential companion for bloggers transitioning to decentralized networks. Debug tools are included for inspecting events on relays.

Key Features

• Publish Hugo Posts: Easily publish posts located in content/posts/*.md directly to Nostr.
• Multiple Frontmatter Support: Handles various frontmatter styles including YAML (---) and TOML (+++).
• Automatic Normalization: Automatically normalizes tags and dates for consistency.
• Dry-Run Mode: Preview events before publishing to ensure accuracy.
• Debug and Fetching Tools: Includes a debug script to retrieve existing articles from relays, enhancing oversight.
• Deletion Management: Send deletion events for all articles easily with a dedicated script.
• Resilient to Relay Failures: Supports multiple relays and continues operations even when one relay is offline.
• Flexible Configuration: Utilize environment variables for dynamic project configuration.
• Metadata Storage: All published events are stored in markdown files with corresponding metadata (nostr_id).
• Sync Capability: Fetch and synchronize posts from Nostr back to Hugo when they are missing.
• Specific Article Deletion: Articles can be deleted by adding delete: true in the frontmatter.
• Relay List Update: Update the relay list and modify event IDs through frontmatter.

Environment Configuration

To tailor the project to specific needs, configure it using environment variables in a .env file or export them directly. An example configuration might look like:

POSTS_DIR="FULLPATH_PROJECT_DIR/content/posts"
RELAY_LIST="wss://relay.emre.xyz"
DRY_RUN=1
NOSTR_PRIVATE_KEY="nsecXXX"

Load these variables automatically with dotenv or export them as needed in your shell.

Available Scripts

1. Publish Posts (index.js)

   • Publishes Hugo posts with a straightforward command:

   npm run publish
   

   • Features include reading Markdown files, normalizing dates, and supporting dry-run mode.
   • To preview posts before going live:

   npm run dry-run
   

2. Fetch Existing Articles (debug.js)

   • Retrieve existing kind:30023 articles using:

   npm run debug
   

   • Connects to all relays in the list, continuing the fetch process even if one fails.

3. Delete Articles (delete.js)

   • Send deletion events for articles with:

   npm run delete
   

   • This command ensures the process continues smoothly across relays and requires a private key for signing.

Example Workflow

1. Preview posts without publishing: npm run dry-run
2. Publish posts to Nostr: npm run publish
3. Fetch existing articles: npm run debug
4. Delete all articles if needed: npm run delete-all
5. Delete specific articles via frontmatter metadata: npm run delete
6. Sync posts from the Nostr network back to Hugo: npm run sync
7. Update relay list and event IDs from frontmatter: npm run update

Additional Notes

• The dry-run mode is a recommended practice to prevent publishing errors.
• Posts with older timestamps may be rejected by certain relays; hence, timestamp normalization is in effect.
• Deletion requests will only succeed if the original public key was used during publication.
• This tool offers resilience against relay failures for uninterrupted service.

Dependencies

• Node.js (ESM)
• nostr-tools
• Glob
• File System (fs)
• dotenv (optional for .env support)

Contributing

Contributions are welcomed. Users can open issues or submit pull requests for enhancements or bug fixes.