@chriswiegman/hugo-tools 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
+and is generated by [Changie](https://github.com/miniscruff/changie).
+
+## 0.1.0 - 2026-05-04
+
+### Features
+
+* Initial test release

package/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2026 Chris Wiegman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# hugo-tools
+
+A collection of CLI tools for Hugo bloggers. Run them directly from the root of your Hugo site via `npx` or install globally.
+
+## Requirements
+
+- Node.js 18 or later
+
+## Installation
+
+**Run without installing (recommended):**
+
+```sh
+npx -p @chriswiegman/hugo-tools <command> [args]
+```
+
+For example:
+
+```sh
+npx -p @chriswiegman/hugo-tools draft
+npx -p @chriswiegman/hugo-tools publish content/drafts/my-post.md now
+```
+
+**Install locally in your Hugo project:**
+
+```sh
+npm install --save-dev @chriswiegman/hugo-tools
+```
+
+Then run commands via `npx` (no `-p` flag needed once installed) or add them as scripts in your `package.json`:
+
+```json
+{
+  "scripts": {
+    "publish": "publish",
+    "extract-tags": "extract-tags"
+  }
+}
+```
+
+**Or install globally and run from any Hugo site root:**
+
+```sh
+npm install -g @chriswiegman/hugo-tools
+publish content/drafts/my-post.md now
+```
+
+All commands must be run from the **root of your Hugo site**.
+
+---
+
+## Configuration
+
+Run `config` from your Hugo site root to generate the file with all defaults:
+
+```sh
+config
+```
+
+Or create `.hugo-tools.json` manually:
+
+```json
+{
+  "timezone": "America/Chicago",
+  "postsDir": "content/posts",
+  "draftsDir": "content/drafts",
+  "notesDir": "content/notes",
+  "booksDir": "content/books",
+  "imagesDir": "assets/images",
+  "vscodeDir": ".vscode"
+}
+```
+
+All fields are optional. Shown values are the defaults.
+
+---
+
+## Commands
+
+### `config`
+
+Generates a `.hugo-tools.json` config file in the current directory with all default values.
+
+```sh
+config
+```
+
+Run this once after installing to get a config file you can edit. Exits with an error if `.hugo-tools.json` already exists.
+
+---
+
+### `vscode`
+
+Scaffolds VS Code configuration for your Hugo site in your `vscodeDir` (default `.vscode/`).
+
+```sh
+vscode
+```
+
+Creates three files if they don't already exist — existing files are left untouched:
+
+| File | Purpose |
+|---|---|
+| `tasks.json` | Tasks for `draft`, `add-tags`, `publish` (now & later), and `pick-image` |
+| `extensions.json` | Recommends the markdown word-count and spell-checker extensions |
+| `settings.json` | Markdown editor settings (snippet suggestions, word-based suggestions off) |
+
+---
+
+### `draft`
+
+Creates a new draft file in your `draftsDir` and opens it in VS Code.
+
+```sh
+draft
+```
+
+Generates a timestamp-based filename (`YYYYMMDD-HHMMSS.md`) using your configured timezone, writes the standard draft front matter with a blank title and placeholder lists, and prints the path. No `date:` line is written — fill in the title before publishing.
+
+**Generated front matter:**
+
+```yaml
+---
+title: ""
+description: ""
+draft: true
+images:
+  -
+categories:
+  -
+tags:
+  -
+---
+```
+
+---
+
+### `publish`
+
+Publishes a Hugo draft post by moving it from your drafts directory to the appropriate content directory and updating its front matter.
+
+```sh
+publish <draft-path> [now|later] [YYYY-MM-DD]
+```
+
+**Examples:**
+
+```sh
+# Publish immediately
+publish content/drafts/my-post.md now
+
+# Schedule for a future date (prompts if date omitted)
+publish content/drafts/my-post.md later 2026-06-01
+```
+
+**What it does:**
+
+- Sets `draft: false` and `date:` to now or 08:00 on the scheduled date (in your configured timezone)
+- Moves the file to `content/posts/YYYY/MM-DD-slug.md`
+- Short posts (under 200 words) without categories are treated as notes and moved to `content/notes/` instead
+- Warns if the draft already had a different `date:` value
+
+**Requirements for posts** (not notes):
+
+- A `title:` in front matter
+- At least one tag
+
+---
+
+### `extract-tags`
+
+Scans all posts in your `postsDir` and writes two files to your `vscodeDir`:
+
+- `tags-categories.json` — sorted list of all tags and categories with usage counts
+- `markdown.code-snippets` — VSCode snippet definitions for autocomplete
+
+```sh
+extract-tags
+```
+
+Run this periodically to keep your tag/category list fresh. The snippet abbreviation map in [src/extract-tags.js](src/extract-tags.js) is pre-populated with some common shorthands — edit it to match your own taxonomy.
+
+---
+
+### `add-tags`
+
+Interactive prompt to select categories and tags from your existing taxonomy, then prints the formatted front matter block to paste into a draft.
+
+```sh
+add-tags
+```
+
+Requires `extract-tags` to have been run at least once.
+
+---
+
+### `pick-image`
+
+Lists images in your `imagesDir` for the current year/month, lets you pick one, and copies the Hugo-relative path to the clipboard.
+
+```sh
+pick-image
+```
+
+Clipboard support: macOS (`pbcopy`), Windows (`clip`), Linux (`xclip`, `xsel`, or `wl-copy` — whichever is available).
+
+---
+
+### `import-books`
+
+Imports books from a [Goodreads CSV export](https://www.goodreads.com/review/import) into Hugo content files under `booksDir`.
+
+```sh
+import-books path/to/goodreads_library_export.csv
+```
+
+**What it does:**
+
+- Creates `content/books/<author-slug>/<title-slug>.md` for each book on your "read" shelf
+- Front matter includes title, author, star rating, finish date(s), and links to Amazon, Open Library, and Goodreads
+- Any Goodreads review text becomes the file body
+- Safe to re-run: existing files are matched by Goodreads ID or ISBN, finish dates are merged, and unchanged files are skipped
+- If a book's title changed in Goodreads, the file is renamed automatically
+
+**To export from Goodreads:** Account → My Books → Import and Export → Export Library.
+
+---
+
+## Contributing
+
+Issues and PRs welcome at <https://github.com/ChrisWiegman/hugo-tools>.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@chriswiegman/hugo-tools",
+  "version": "0.1.0",
+  "description": "A set of tools to make blogging easier with Hugo.",
+  "keywords": [
+    "hugo",
+    "blogging",
+    "drafts",
+    "publishing"
+  ],
+  "homepage": "https://github.com/ChrisWiegman/hugo-tools#readme",
+  "bugs": {
+    "url": "https://github.com/ChrisWiegman/hugo-tools/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChrisWiegman/hugo-tools.git"
+  },
+  "license": "MIT",
+  "author": "Chris Wiegman <contact@chriswiegman.com>",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "CHANGELOG.md"
+  ],
+  "bin": {
+    "config": "src/config-init.js",
+    "vscode": "src/vscode.js",
+    "extract-tags": "src/extract-tags.js",
+    "add-tags": "src/add-tags.js",
+    "draft": "src/draft.js",
+    "pick-image": "src/pick-image.js",
+    "publish": "src/publish.js",
+    "import-books": "src/book.mjs"
+  },
+  "scripts": {
+    "lint": "eslint src/",
+    "test": "node --test src/book.test.mjs src/publish.test.mjs src/extract-tags.test.mjs src/draft.test.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "changie": "^1.24.0",
+    "eslint": "^10.3.0",
+    "globals": "^17.6.0"
+  }
+}

package/src/add-tags.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+/**
+ * Interactive script to help add categories and tags to Hugo draft frontmatter.
+ * Reads from the extracted tags-categories.json file.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const config = require('./config');
+
+const DATA_FILE = path.join(process.cwd(), config.vscodeDir, 'tags-categories.json');
+
+/**
+ * Display menu and get user selection
+ */
+async function getSelection(prompt, options) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    console.log(`\n${prompt}`);
+    options.forEach((opt, idx) => {
+      console.log(`  ${idx + 1}. ${opt}`);
+    });
+    console.log(`  0. Done/Skip`);
+
+    rl.question('\nEnter number: ', (answer) => {
+      rl.close();
+      const num = parseInt(answer, 10);
+      if (num === 0) {
+        resolve(null);
+      } else if (num > 0 && num <= options.length) {
+        resolve(options[num - 1]);
+      } else {
+        console.log('Invalid selection');
+        resolve(null);
+      }
+    });
+  });
+}
+
+/**
+ * Get multiple selections
+ */
+async function getMultipleSelections(prompt, options) {
+  const selections = [];
+  let done = false;
+
+  while (!done) {
+    const remaining = options.filter(opt => !selections.includes(opt));
+    if (remaining.length === 0) {
+      break;
+    }
+
+    const selection = await getSelection(
+      selections.length === 0 ? prompt : `${prompt} (Selected: ${selections.join(', ')})`,
+      remaining
+    );
+
+    if (selection === null) {
+      done = true;
+    } else {
+      selections.push(selection);
+    }
+  }
+
+  return selections;
+}
+
+/**
+ * Format frontmatter list
+ */
+function formatList(items) {
+  if (items.length === 0) {
+    return '  -';
+  }
+  return items.map(item => `  - ${item}`).join('\n');
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  config.requireHugoSite();
+
+  console.log('=== Hugo Draft Tags & Categories Helper ===\n');
+
+  // Check if data file exists
+  if (!fs.existsSync(DATA_FILE)) {
+    console.error(`Error: Data file not found at ${DATA_FILE}`);
+    console.error('Run "extract-tags" first to generate the data file.');
+    process.exit(1);
+  }
+
+  // Load data
+  const data = JSON.parse(fs.readFileSync(DATA_FILE, 'utf8'));
+
+  console.log(`Loaded ${data.categories.length} categories and ${data.tags.length} tags`);
+  console.log(`(Generated from ${data.stats.totalFiles} posts on ${new Date(data.stats.generatedAt).toLocaleDateString()})\n`);
+
+  // Get category selection
+  const category = await getSelection(
+    'Select a category:',
+    data.categories
+  );
+
+  // Get tag selections
+  const tags = await getMultipleSelections(
+    'Select tags (you can select multiple):',
+    data.tags
+  );
+
+  // Generate output
+  console.log('\n=== Generated Frontmatter ===\n');
+
+  if (category) {
+    console.log('categories:');
+    console.log(`  - ${category}`);
+  } else {
+    console.log('categories:');
+    console.log('  -');
+  }
+
+  console.log('tags:');
+  console.log(formatList(tags));
+
+  console.log('\n=== Copy the above into your draft frontmatter ===\n');
+}
+
+// Handle Ctrl+C gracefully
+process.on('SIGINT', () => {
+  console.log('\n\nCancelled.');
+  process.exit(0);
+});
+
+main().catch(err => {
+  console.error('Error:', err);
+  process.exit(1);
+});