@ainame/tuzuru 0.0.20 → 0.1.1

package/README.md

@@ -1,34 +1,258 @@
-@ainame/tuzuru (npm)
+# Tuzuru
 
-NPM wrapper for the Tuzuru static blog generator.
+![logo](.github/assets/logo.png)
 
-What it does
-- Installs prebuilt Tuzuru binary for your platform (macOS universal or Linux x64/aarch64) during npm install.
-- Exposes a `tuzuru` executable on your PATH.
-- Sets `TUZURU_RESOURCES` automatically so Tuzuru can locate its resource bundle.
+Tuzuru (綴る) is dead-simple static **blog** generator CLI that uses Git to manage your blog's metadata.
 
-Install
-- Latest published: `npm i -g @ainame/tuzuru`
-- Or as a dev dependency: `npm i -D @ainame/tuzuru`
+Instead of writing YAML front matter, you just write and save your plain Markdown files to Git. Tuzuru automatically pulls metadata like the publication date and author information from the Git commit history.
 
-Usage
-- `tuzuru --help`
-- `tuzuru generate`
-- `tuzuru init`
+This means you can focus on what you're writing, not on remembering syntax. It's a simpler, more lightweight way to manage your blog.
 
-Version mapping
-- The npm package version should match the Tuzuru GitHub release tag (no `v` prefix). The installer fetches the asset for that tag.
-- If the package version is `0.0.0`, the installer falls back to the latest release via the GitHub API.
+## Motivation
 
-Maintainers: how to publish
-1) Create a Tuzuru release and note the version (e.g. `1.2.3`). Ensure assets exist named:
-   - `tuzuru-1.2.3-macos-universal.tar.gz`
-   - `tuzuru-1.2.3-linux-x86_64.tar.gz`
-   - `tuzuru-1.2.3-linux-aarch64.tar.gz`
-2) Update `npm/package.json` version to the same `1.2.3`.
-3) From the `npm/` directory, run:
-   - `npm publish --access public`
+Years ago, I built a blog with Hugo, but eventually stopped updating it. When I recently wanted to start again, I found it tough to remember and re-learn how to use it.
 
-CI note
-- This package uses the GitHub REST API unauthenticated during installation to resolve the asset URL. On heavily parallelized CI, consider setting `GITHUB_TOKEN` in the environment to increase rate limits.
+I wanted a simple, intuitive blogging tool, but none I tried felt quite right. So, I decided to build my own.
 
+Tuzuru is designed with these core principles:
+
+* Plain Markdown: No YAML front matter.
+* Simple Routing: A routing system built specifically for blogs.
+* No JavaScript Framework: Lightweight and fast.
+* Single Binary Installation: Avoids environment setup for tools that you may not use day-to-day
+
+## Installation
+
+### Homebrew (macOS)
+
+```bash
+brew tap ainame/tuzuru https://github.com/ainame/Tuzuru
+brew install tuzuru
+```
+
+### Manual Build
+
+```bash
+swift build -c release
+cp .build/release/tuzuru /path/to/bin
+```
+
+## Getting started
+
+You first need to set up a Git repo locally.
+
+```bash
+mkdir new-blog
+cd new-blog
+git init
+
+# Initialize a blog project
+# This adds `assets`, `contents`, `templates` directories and `tuzuru.json`
+tuzuru init
+
+git add .
+git commit -m "init commit"
+```
+
+Then create a markdown file under the `contents` directory and do `git commit`.
+
+``` bash
+emacs contents/first-blog-post.md
+git add contents/first-blog-post.md
+git commit -m "First post"
+```
+
+When you make `git commit` becomes your post's published date.
+Specifically, the first commit's Author Date for a markdown file under `contents` is the published date and also, author name will be taken from Git's config.
+
+Now it's time to build your blog.
+
+``` bash
+tuzuru generate
+```
+
+You can now see the `blog` directory that can be deployed to GitHub Pages or your favorite HTTP server.
+
+For local development, use the built-in serve command:
+
+``` bash
+tuzuru serve
+```
+
+This starts a local HTTP server at `http://localhost:8000` with auto-regeneration enabled. When you modify source files, the blog will be automatically rebuilt on the next request.
+
+### Built-in layout
+
+The built-in layout is a great starting point and is easy to customize. It already includes [github-markdown-css](https://github.com/sindresorhus/github-markdown-css) and [highlight.js](https://highlightjs.org/) to make writing tech blog posts a breeze.
+
+
+![screenshot](.github/assets/screenshot.png)
+
+### Example project structure
+
+```
+my-blog/
+├── contents/
+│   ├── hello-world.md          # → /hello-world
+│   ├── tech/
+│   │   └── swift-tips.md       # → /tech/swift-tips (listed on /tech)
+│   └── unlisted/
+│       └── about.md            # → /about (not listed anywhere. You can link to /about from layout.mustache manually)
+├── templates/
+│   ├── layout.mustache
+│   ├── post.mustache
+│   └── list.mustache
+├── assets/
+│   └── main.css
+└── tuzuru.json
+```
+
+### Demo
+
+You can see Tuzuru in action with this demo blog hosted on GitHub Pages:
+
+- **Live Demo**: [https://ainame.tokyo/tuzuru-demo/](https://ainame.github.io/tuzuru-demo/)
+- **Source Repository**: [https://github.com/ainame/tuzuru-demo](https://github.com/ainame/tuzuru-demo)
+
+This demo showcases the built-in layout and demonstrates how Tuzuru generates clean, lightweight blog pages from plain Markdown files.
+
+## How it works
+
+### Layout and customization
+
+Tuzuru supports two types of pages.
+
+1. Post - a blog article
+2. List - a listing page generated automatically
+
+You can customize these layouts using three Mustache files:
+
+* templates/layout.mustache - Base layout
+* templates/post.mustache - main part of post page
+* templates/list.mustache - main part of list page
+
+For more on syntax, see the documentation.
+https://docs.hummingbird.codes/2.0/documentation/hummingbird/mustachesyntax/
+
+### Listing and Unlisted Pages
+
+By default, any Markdown file in the `contents` directory is automatically listed on:
+
+* The home page (`/`) based on your configuration.
+* Yearly archive pages (e.g., `/2025`, `/2024`).
+* Category pages for files in subdirectories (e.g., `contents/tech/swift.md` is listed on `/tech`).
+
+You can add an unlisted page by placing it in `contents/unlisted/`. These pages won't be listed anywhere automatically, but you can link to them manually from your templates.
+
+### Assets
+
+The `tuzuru init` command creates an assets directory containing `main.css`. The tuzuru generate command copies all files from this directory to `blog/assets`.
+
+To prevent browser cache issues, use the `{{buildVersion}}` variable in your templates.
+
+
+```mustache
+<link rel="stylesheet" href="{{assetsUrl}}main.css?{{buildVersion}}">
+```
+
+### tuzuru.json
+
+`tuzuru.json` is the main configuration file, though you can omit most settings if you stick to the defaults.
+
+
+```javascript
+{
+  // `metadata` is the only mandatory section.
+  "metadata" : {
+    "blogName" : "My Blog",
+    "copyright" : "My Blog",
+    "description" : "My personal blog", // Meta description for SEO
+    "baseUrl" : "https://example.com/",  // Production URL
+    "locale" : "en_GB" // Affects the published date format
+  },
+  // `output` for configuring output options
+  "output" : {
+    "directory" : "blog", // The output directory
+    "homePageStyle" : "all", // "all", "pastYear", or a number (last X posts)
+    "routingStyle" : "subdirectory" // "subdirectory" (e.g., /hello-world) or "direct" (e.g., /hello-world.html)
+  },
+  // `sourceLayout` to customize the default directory structure (typically not needed)
+  "sourceLayout" : {
+    "assets" : "assets",
+    "contents" : "contents",
+    "imported" : "contents/imported",
+    "templates" : {
+      "layout" : "templates/layout.mustache",
+      "list" : "templates/list.mustache",
+      "post" : "templates/post.mustache"
+    },
+    "unlisted" : "contents/unlisted"
+  }
+}
+```
+
+## Import posts from Hugo project
+
+You can import Markdown files from a Hugo project. Tuzuru will parse the YAML front matter to get the title, author, and date, then remove it. Each imported Markdown file will be added as an individual Git commit.
+
+```bash
+tuzuru import /path/to/import-target-dir # import them to ./contents/imported by default
+tuzuru import /path/to/import-target-dir --destination /path/to/import
+```
+
+## Amend published date or author
+
+Need to change a post's published date or author without rewriting your Git history? Use the amend command.
+
+```bash
+# Update published date
+tuzuru amend contents/my-post.md --published-at "2023-12-01"
+
+# Update author
+tuzuru amend contents/my-post.md --author "New Author"
+
+# Update both
+tuzuru amend contents/my-post.md --published-at "2023-12-01 10:30:00 +0900" --author "New Author"
+```
+
+The command supports flexible date formats:
+
+- `2023-12-01` (date only)
+- `2023-12-01 10:30:00` (date and time)
+- `2023-12-01T10:30:00Z` (ISO 8601 UTC)
+- `2023-12-01 10:30:00 +0900` (with timezone)
+
+This command creates a special marker commit that Tuzuru recognizes for post metadata, leaving your history clean.
+
+## Local Development Server
+
+Tuzuru includes a built-in HTTP server for local development:
+
+```bash
+# Basic usage (serves on port 8000)
+tuzuru serve
+
+# Custom port
+tuzuru serve --port 3000
+
+# Custom directory (default is 'blog')
+tuzuru serve --directory my-output
+
+# Custom config file
+tuzuru serve --config my-config.json
+```
+
+### Auto-regeneration
+
+The serve command automatically watches for changes in your source files and regenerates the blog when needed:
+
+- **Content files**: Watches `contents/` and `contents/unlisted/` directories
+- **Asset files**: Watches the `assets/` directory  
+- **Templates**: Watches template files for changes
+
+When files are modified, the blog is regenerated on the next HTTP request, providing a seamless development experience without manual rebuilds.
+
+## Build Requirements
+
+- Swift 6.1+
+- macOS v15+

package/{scripts → npm/scripts}/install.js

@@ -27,7 +27,7 @@ function fail(msg) {
   process.exit(1);
 }
 
-const pkg = require('../package.json');
+const pkg = require('../../package.json');
 const version = (pkg.version || '').trim();
 if (!version || version === '0.0.0') {
   log('Package version is 0.0.0; attempting to install latest release via GitHub API');

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ainame/tuzuru",
-  "version": "0.0.20",
+  "version": "0.1.1",
   "description": "Tuzuru static blog generator (npm wrapper around prebuilt binaries)",
   "license": "MIT",
   "private": false,
   "bin": {
-    "tuzuru": "bin/tuzuru.js"
+    "tuzuru": "npm/bin/tuzuru.js"
   },
   "os": [
     "darwin",
@@ -27,12 +27,12 @@
     "url": "https://github.com/ainame/Tuzuru/issues"
   },
   "scripts": {
-    "postinstall": "node scripts/install.js"
+    "postinstall": "node npm/scripts/install.js"
   },
   "files": [
-    "bin/",
-    "scripts/",
-    "vendor/",
+    "npm/bin/",
+    "npm/scripts/",
+    "npm/vendor/",
     "README.md"
   ]
 }