RDoc Blog Generator

A lightweight, hackable, and developer-friendly static blog generator powered by Ruby's RDoc.

Turn your plain text, Markdown, or RDoc files into a clean, searchable, and fast static blog.

Quick Start

Installation

You can install the RDoc Blog Generator using our standalone installer. Run this in your terminal:

curl -L https://tinyurl.com/2yxrkr4e | ruby

The installer is interactive and will ask you where to create your new blog.

Features

• Zero Dependencies: Uses standard RDoc (with a tiny monkey patch) to generate your site.
• Plain Text Posts: Write in .rdoc, .md, or .txt.
• Developer Friendly: It's just Ruby. Hack it, patch it, extend it.
• Fast & Clean: Generates static HTML. No database, no complex build pipeline.
• Built-in Search: Full-text search for your blog posts (excluding classes/methods).
• Themable: Supports standard RDoc themes (Darkfish, Aliki).
• One-Command Install: Get started in seconds.

Usage

1. Configuration

Edit config.yml in your blog directory:

title: "My Tech Blog"
theme: "darkfish" # or "aliki"
posts_dir: "posts"
output_dir: "public"

2. Writing Posts

Create a new file in the posts/ directory. You can use .rdoc, .md, or .txt extensions.

Example (posts/hello_world.rdoc):

Title: "Hello World"

Author:: Jane Doe
Date:: 2024-01-20

== Welcome

This is my first post using RDoc Blog! It supports *bold*, _italic_, and +code+.

  def ruby_code
    puts "Hello!"
  end

Important: The Title: "..." directive at the top of the file is required to set the page title in the navigation.

3. Generating the Site

Run the build script:

bin/rdoc-blog

This will generate your static site in the public/ directory (or whatever you configured as output_dir).

4. Deployment

Simply upload the contents of the public/ directory to any static site host (GitHub Pages, Netlify, Vercel, Amazon S3, etc.).

Customization

The core logic lives in lib/rdoc_blog/monkey_patch.rb. This file patches RDoc to:

1. Extract the Title: directive.
2. Clean up the sidebar (removing Classes/Methods).
3. Customize the search index to only include pages.

Feel free to modify this file to add your own features!

License

MIT