Fledermaus: Batman’s toolbelt for static site generation

Infinitely extensible simple static site generator.

Based on JSX, Remark, Richtypo, Highlight.js and Intl MessageFormat.

Features

• JSX templates
• I18n
• Syntax highlighting
• Custom Markdown tags
• Tools to generate custom pages (not based on Markdown source)
• Tools for pagination, etc.
• RSS feed generation
• Simple and fast
• Very customizable

Installation

$ npm install --save-dev fledermaus

Examples below are written in ES6, so you need Babel to run them (but Babel is not required to use Fledermaus):

$ npm install --save-dev babel-cli babel-preset-tamia babel-plugin-transform-react-jsx

I also recommend to use http-server (or tamia-build) to preview your site locally:

$ npm install --save-dev http-server

And chokidar to recompile site on changes in templates and sources:

$ npm install --save-dev chokidar-cli

Your package.json should look like this:

{
  "name": "example.com",
  "version": "1.0.0",
  "private": true,
  "devDependencies": {
    "babel-cli": "~6.4.0",
    "babel-plugin-transform-react-jsx": "~6.7.4",
    "babel-preset-tamia": "~6.5.0",
    "chokidar-cli": "~1.2.0",
    "http-server": "~0.8.5",
    "fledermaus": "~4.1.0"
  },
  "scripts": {
    "start": "npm run server & npm run watch",
    "build": "babel-node src",
    "build:watch":
      "chokidar templates source src -c 'babel-node src'",
    "server": "http-server public -p 4242 -o"
  }
}

Now you can use npm run build to build your site and npm start to run a local server.

Your .babelrc should look like this:

{
  "presets": ["tamia"],
  "plugins": [
    [
      "transform-react-jsx",
      {
        "pragma": "vdo"
      }
    ]
  ]
}

Recommended folder structure

.
├── src           # Generator code
│   └── index.js
├── config        # Configs
│   └── base.yml  # Base config
│   └── en.yml    # Language specific configs
│   └── ru.yml
├── source        # Markdown sources
├── templates     # JSX templates
├── public        # Generated HTML files

Examples

Super simple static site

No config, everything in one folder.

index.js:

import {
  start,
  loadSourceFiles,
  generatePages,
  savePages,
  createMarkdownRenderer,
  createTemplateRenderer,
  helpers
} from 'fledermaus';

start('Building the page...');

process.chdir(__dirname);

let renderMarkdown = createMarkdownRenderer();
let renderTemplate = createTemplateRenderer({ root: '.' });

let documents = loadSourceFiles('.', ['md'], {
  renderers: {
    md: renderMarkdown
  }
});

let pages = generatePages(
  documents,
  { assetsFolder: 'public' },
  helpers,
  { jsx: renderTemplate }
);

savePages(pages, 'public');

You can find examples of templates and source files here.

Static site

src/index.js:

import {
  start,
  loadConfig,
  loadSourceFiles,
  generatePages,
  savePages,
  createMarkdownRenderer,
  createTemplateRenderer,
  helpers
} from 'fledermaus';

start('Building the site...');

let config = loadConfig('config');
let options = config.base;

let renderMarkdown = createMarkdownRenderer();
let renderTemplate = createTemplateRenderer({
  root: options.templatesFolder
});

let documents = loadSourceFiles(
  options.sourceFolder,
  options.sourceTypes,
  {
    renderers: {
      md: renderMarkdown
    }
  }
);

let pages = generatePages(documents, config, helpers, {
  jsx: renderTemplate
});

savePages(pages, options.publicFolder);

config/base.yml:

sourceFolder: source
sourceTypes:
  - md
  - html
templatesFolder: templates
assetsFolder: public
publicFolder: public

lang: en
url: http://sapegin.me

title: Artem Sapegin’s Home Page

You can find examples of templates and source files here.

Multilingual blog

• Two languages;
• pagination;
• cut;
• tags;
• RSS feed.

src/index.js:

import {
  start,
  loadConfig,
  loadSourceFiles,
  generatePages,
  savePages,
  paginate,
  orderDocuments,
  groupDocuments,
  createMarkdownRenderer,
  createTemplateRenderer,
  helpers
} from 'fledermaus';

start('Building the blog...');

let config = loadConfig('config');
let options = config.base;

// Remove language (en or ru) from a URL
let removeLang = url => url.replace(/(en|ru)\//, '');

let renderMarkdown = createMarkdownRenderer();
let renderTemplate = createTemplateRenderer({
  root: options.templatesFolder
});

let documents = loadSourceFiles(
  options.sourceFolder,
  options.sourceTypes,
  {
    renderers: {
      md: renderMarkdown
    },
    // Custom front matter field parsers
    fieldParsers: {
      // Save `date` field as a timestamp
      timestamp: (timestamp, attrs) => Date.parse(attrs.date),
      // Convert `date` field to a Date object
      date: (date, attrs) => new Date(Date.parse(date))
    },
    // Cut separator
    cutTag: options.cutTag
  }
);

// Oder by date, newest first
documents = orderDocuments(documents, ['-timestamp']);

// Group posts by language
let documentsByLanguage = groupDocuments(documents, 'lang');
let languages = Object.keys(documentsByLanguage);

documents = languages.reduce((result, lang) => {
  let docs = documentsByLanguage[lang];
  let newDocs = [];

  // Translations
  // Append all posts with a field indicating whether this post has a translation
  // (post with the same URL in another language)
  let translationLang = lang === 'ru' ? 'en' : 'ru';
  let hasTranslation = url => {
    url = removeLang(url);
    return !!documentsByLanguage[translationLang].find(
      doc => removeLang(doc.url) === url
    );
  };
  docs = docs.map(doc => {
    return {
      ...doc,
      translation: hasTranslation(doc.url)
    };
  });

  // Pagination
  newDocs.push(
    ...paginate(docs, {
      sourcePathPrefix: lang,
      urlPrefix: `/${lang}/`,
      documentsPerPage: options.postsPerPage,
      layout: 'index',
      index: true,
      extra: {
        lang
      }
    })
  );

  // Tags
  let postsByTag = groupDocuments(docs, 'tags');
  let tags = Object.keys(postsByTag);
  newDocs.push(
    ...tags.reduce((tagsResult, tag) => {
      let tagDocs = postsByTag[tag];
      let tagsNewDocs = paginate(tagDocs, {
        sourcePathPrefix: `${lang}/tags/${tag}`,
        urlPrefix: `/${lang}/tags/${tag}`,
        documentsPerPage: options.postsPerPage,
        layout: 'tag',
        extra: {
          lang,
          tag
        }
      });
      return [...tagsResult, ...tagsNewDocs];
    }, [])
  );

  // RSS feed
  newDocs.push({
    sourcePath: `${lang}/feed.xml`,
    url: '/feed.xml',
    layout: 'RSS',
    items: docs.slice(0, options.postsInFeed),
    title: config[lang].title,
    description: config[lang].description,
    copyright: config[lang].author,
    imageUrl: '/images/userpic.jpg',
    lang
  });

  return [...result, ...docs, ...newDocs];
}, []);

let pages = generatePages(documents, config, helpers, {
  jsx: renderTemplate
});

savePages(pages, options.publicFolder);

config/base.yml:

sourceFolder: source
sourceTypes:
  - md
  - html
templatesFolder: templates
assetsFolder: public
publicFolder: public
postsPerPage: 10
postsInFeed: 15
cutTag: <!-- cut -->

config/en.yml:

url: http://blog.sapegin.me
title: Artem Sapegin’s Blog
description: 'Blog of a Berlin based font-end developer who works at Here, shoots photos and makes something awesome on the internet.'
author: Artem Sapegin
email: [email protected]
tagNames:
  css: CSS
  html: HTML
  javascript: JavaScript
  thoughts: Thoughts
  tools: Tools

You can find examples of templates and source files here.

Advanced Usage

Custom helpers

helpers.js:

import { cleanHtml } from 'fledermaus/lib/util';

/* eslint-disable no-invalid-this */

// Page title
export function getPageTitle(suffix) {
  if (this.pageTitle) {
    return this.pageTitle;
  }
  if (this.title) {
    if (suffix === undefined) {
      suffix = ' — ' + this.option('title');
    }
    return cleanHtml(this.title) + (suffix || '');
  }
  return this.option('title');
}

src/index.js:

import {
  // ...
  helpers as defaultHelpers
} from 'fledermaus';
import * as customHelpers from './helpers';

// ...

let helpers = { ...defaultHelpers, ...customHelpers };

// ...

let pages = generatePages(documents, config, helpers, {
  jsx: renderTemplate
});

// ...

Template:

<title><%= @getPageTitle() %></title>

Custom tags

src/index.js:

import {
  // ...
  createMarkdownRenderer
} from 'fledermaus';
import { MarkdownRenderer } from 'fledermaus/lib/renderers/markdown';

let renderMarkdown = createMarkdownRenderer({
  customTags: {
    embed: ({ id, title }) => {
      return `
        <div class="embed">
          <div class="embed__content embed-${id}">
            <div class="embed-${id}-i" id="${id}"></div>
          </div>
          <div class="embed__description">${title}</div>
        </div>
      `;
    }
  }
});

// ...

Markdown source (on a separate line):

<x-embed id="ironman" title="Use keys ← and →, mouse or thumbs and have the pleasure of Ivan’s sprites.">

Tweaking Markdown rendering

src/index.js:

import {
  // ...
  createMarkdownRenderer
} from 'fledermaus';
import visit from 'unist-util-visit';

function remarkScreenshot(processor) {
  return ast =>
    visit(ast, 'paragraph', node => {
      // Screenshots: /images/mac__shipit.png or /images/win__shipit.png
      let child = node.children && node.children[0];
      if (child && child.type === 'image') {
        let m = child.url.match(/\/(\w+)__/);
        if (m) {
          node.children = null;
          node.type = 'html';
          node.value = `<div class="screenshot screenshot_${
            m[1]
          }"><img src="${child.url}" alt="${child.title ||
            ''}"></div>`;
        }
      }
    });
}
let renderMarkdown = createMarkdownRenderer({
  plugins: [remarkScreenshot]
});

Deploying to GitHub Pages

Install gh-pages module:

$ npm install --save-dev gh-pages

Add an npm script to your package.json:

{
  "scripts": {
    "build": "node lib",
    "gh-pages": "gh-pages -d public",
    "deploy": "npm run build && npm run gh-pages"
  }
}

Now you can use npm run deploy to build and upload your site to GitHub Pages.

Showcase

• Artem Sapegin’s site (source)
• Artem Sapegin’s blog (source)
• React Styleguidist (source)

Change log

The change log can be found on the Releases page.

Author

• Artem Sapegin

License

The MIT License, see the included License.md file.