Shinmun - a file based blog engine

Shinmun is a small file based blog engine. Write posts in your favorite editor, track them with git and deploy to Heroku. Small, fast and simple.

• Posts are text files formatted with Markdown, Textile or HTML
• Deploy via git-push
• Easy and fast deploying on Heroku
• Index, category and archive listings
• RSS feeds
• Syntax highlighting provided by Rouge
• TypeScript mini apps - embed interactive TypeScript code in your pages

Install the gems:

$ gem install shinmun

Create a sample blog:

$ shinmun init myblog

This will create a directory with all necessary files. Now start the web server:

$ cd myblog
$ rackup

Browse to the following url:

http://localhost:9292

Voilà, your first blog is up and running!

Posts can be created by using the shinmun command inside your blog folder:

shinmun post 'The title of the post'

Shinmun will then create a post file in the right place, for example in posts/2008/9/the-title-of-the-post.md.

Each blog post is just a text file with a YAML header and a body. The YAML header is surrounded with 2 lines of 3 dashes.

The YAML header has following attributes:

• title: mandatory
• date: posts need one, pages not
• category: a post belongs to one category
• tags: a comma separated list of tags

Example post:

--- 
date: 2008-09-05
category: Ruby
tags: kramdown, markdown
title: Kramdown, a Markdown library
---
This is the summary, which is by definition the first paragraph of the
article. The summary shows up in category listings or the index listing.

Thanks to the fantastic highlighting library Rouge, highlighted code blocks can be embedded easily in Markdown. Rouge supports a wide variety of languages including Ruby, Python, JavaScript, C, Java, HTML, CSS, JSON, YAML, and many more.

To activate Rouge for a code block, you have to declare the language in lower case:

@@ruby

def method_missing(id, *args, &block)
  puts "#{id} was called with #{args.inspect}"
end             

Note that the declaration MUST be followed by a blank line!

Shinmun supports embedding TypeScript mini apps directly in your pages. TypeScript code is compiled to JavaScript using esbuild and embedded as a <script type="module"> block.

Prerequisites: You need to have Node.js and npm installed, then run npm install esbuild in your blog directory.

To embed TypeScript, use @@typescript followed by a blank line and indented code:

@@typescript

const greeting: string = "Hello, World!";
document.body.innerHTML = `<h1>${greeting}</h1>`;

For mini apps that need a container element, specify a container ID:

@@typescript[my-app]

const container = document.getElementById('my-app')!;
container.innerHTML = '<p>Interactive content here!</p>';

This creates a <div id="my-app"></div> before the script.

For larger components (like React), reference external TypeScript/TSX files:

@@typescript-file[my-component](public/apps/my-component.tsx)

This reads the file, compiles it with bundling enabled, and embeds the result. React is automatically loaded from a CDN via import maps.

Example React component (save as public/apps/counter.tsx):

import React, { useState } from 'react';
import { createRoot } from 'react-dom/client';

function Counter() {
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount(c => c + 1)}>
      Count: {count}
    </button>
  );
}

const root = createRoot(document.getElementById('my-component')!);
root.render(<Counter />);

Then in your markdown:

@@typescript-file[my-component](public/apps/counter.tsx)

Note: Each TypeScript block must end with a blank line before the next content paragraph.

+ config.ru
+ pages
  + about.md
+ posts
  + 2007
  + 2008
    + 9
      + my-article.md
+ public
  + styles.css
  + apps              # TypeScript/React components
    + counter.tsx
    + todo.tsx
+ templates
  + 404.rhtml
  + archive.rhtml
  + category.rhtml
  + index.rhtml
  + index.rxml
  + layout.rhtml
  + page.rhtml
  + post.rhtml  

In config.ru you can set the properties of your blog:

blog.config = {
  :language => 'en',
  :title => "Blog Title",
  :author => "The Author",
  :categories => ["Ruby", "Javascript"],
  :description => "Blog description"
}

Layout and templates are rendered by ERB. The layout is defined in templates/layout.rhtml. The content will be provided in the variable @content. A minimal example:

<html>
  <head>
    <title><%= @blog.title %></title>
    <%= stylesheet_link_tag 'style' %>
  </head>
  <body>
     <%= @content %>
  </body>
 </html>

The attributes of a post are accessible via the @post variable:

<div class="article">
 
  <h1><%= @post.title %></h1>
 
  <div class="date">
    <%= human_date @post.date %>
  </div>
 
  <%= @post.body_html %>

  ...      

</div>

Shinmun can generate a static site that you can host on GitHub Pages for free.

Export your blog to static files:

$ shinmun export docs

Commit the docs folder and push to GitHub. Then enable GitHub Pages in your repository settings, selecting the docs folder as the source.

For detailed instructions including GitHub Actions automation and custom domain setup, see the GitHub Pages Guide.

Download or fork the package at my github repository