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: artem@sapegin.me
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
Change log
The change log can be found on the Releases page.
Author
License
The MIT License, see the included License.md file.