@astronomersiva/lego

Lego

A fast Static Site Generator that generates optimised, performant websites.

Tell me more

• Built with NodeJS.
• Supports Nunjucks and Liquid templates.
• Minifies and uglifies JS files(with terser) and autoprefixes and minifies CSS(with PostCSS) files using the provided browserslist to determine transpilation targets.
• Does asset revisioning of CSS, JS and image files.
• Supports PostCSS plugins.
• Images under static will be optimised with imageoptim.
• Code highlighting at build time using highlight.js.
• Automatic sitemap and RSS feeds generation.
• Extracts and inlines critical CSS with critical.
• Supports inlining assets using inline-source.
• Generates images for various resolutions and automatically inserts picture elements with the corresponding source elements.
• Minifies the output HTML.
• Supports including html in md by implementing a custom md syntax. ::: include table.html :::.
• Live-reload during development.
• Copies CNAME to build directory, so will work with GH Pages.
• Implements a cache resulting in faster builds on subsequent runs.

Installation

• Run npm i -g @astronomersiva/lego.

Usage

• Run lego g siteName to create a new site.
• Run lego s / lego serve to run a server.
• Run lego b / lego build to create an optimised build.
• To include an HTML in a markdown file, use ::: include table.html :::.
• To automatically generate images for various resolutions,

::: lego-image src="static/images/${IMAGE}" res="1080,500,320" alt="alternate text" class="img-responsive center-block" :::

• lego also exposes an isDevelopment variable that you can use to disable certain stuff in development. For example, analytics.

{% unless isDevelopment %}
  <!-- analytics code -->
{% endunless %}

Directory structure

.
├── CNAME
├── README.md
├── layouts
│   ├── post.html             // will be used for markdown posts
│   └── tags.html             // will be used to generate tag wise listing of posts
├── pages
│   ├── 404.html
│   └── about.html            // each of these will be put under a separate folder in build
│   └── index.html
├── data
│   ├── authors.yml
│   └── speakers.yaml         // will be available as data.authors and data.speakers
├── posts
│   ├── post.md
│   └── another-post.md
└── static
    ├── css
    │   └── styles.css        // possible to have sub folders
    ├── images
    └── js
        └── custom-scripts.js

Configuration file

Every lego project has a lego.js file at the root. It should have the following contents:

• url: This is needed to generate sitemaps. Example, 'https://www.sivasubramanyam.me/'.
• critical: This can be used if critical CSS is to be inlined. Using this might significantly increase production build times. Takes options applicable to critical. Example,

critical: {
  inline: true,
  dimensions: [
    {
      height: 800,
      width: 470
    }, {
      height: 900,
      width: 1200
    }
  ],
  penthouse: {
    timeout: 150000
  }
}

• flatUrls: If this option is set as true, the URL of generated posts will not include directories. For example, in this tree structure,

.
└── posts
    ├── travel
    │   └── nepal.md
    └── i-love-js.md

the URL of nepal.md will be site.com/nepal if this option is true. By default(false), the URL of this post would be site.com/travel/nepal. This option will be overridden if the post's front-matter has a url field.

• inlineSource: If this option is set as true, assets in tags that contain the inline attribute will be inlined. You can also pass options supported by inline-source.
• server: Options for the development server. Refer live-server.
• server.ssl: If this option is set as true, lego will start an HTTPS development server using a self-signed certificate. Please note that self-signed certificates might not be accepted by many browsers by default. If you would like to use your own cert and key files, you can do so by passing them to this option like,

ssl: {
  key: 'server.key',
  cert: 'server.crt'
}

• htmlMinifier - Options for html-minifier. Defaults are

{
  collapseWhitespace: true,
  minifyJS: true,
  minifyCSS: true,
  removeComments: true
}

• md: You can pass an array of plugins or pass an array of block-level custom containers that can be used by the Markdown parser. Refer markdown-it-container.

const emoji = require('markdown-it-emoji');
const toc = require('markdown-it-table-of-contents');

{
  md: {
    containers: [
      {
        name: 'myCustomContainer',
        options: {
          validate: function(params) {}
          render: function(tokens, idx) {}
        }
      }
    ],
    plugins: [
      emoji,
      [
        toc, {
          containerClass: 'toc',
        }
      ]
    ]
  }
}

• postCSSPlugins: An array of PostCSS plugins. These will be used in addition to cssnano that is already included in lego.

{
  postCSSPlugins: [
    'precss',
    'postcss-nested'
  ]
}

• rss: Options to pass to the RSS feeds generator. Refer rss feedOptions. Categories and Publishing Date will be automatically populated.

Benchmarks

To run benchmarks, run

$ cd benchmarks
$ yarn
$ node generator.js
$ node --max-old-space-size=4096 index.js

It will run benchmarks against jekyll the following data:

• Uses Nunjucks as the templating language.
• 500 posts.
• Each post contains 150 paragraphs.
• Each paragraph contains 150 random words.
• The size of each post is about 150kb.
• lego will be run with its cache disabled.
• No static files are present.

While jekyll produces only a build, lego does HTML minification as well.

Results:

jekyll x 0.04 ops/sec ±3.48% (5 runs sampled)
lego without cache x 0.24 ops/sec ±11.03% (5 runs sampled)
lego with cache x 0.35 ops/sec ±2.36% (5 runs sampled)
Fastest is lego with cache

License

MIT © Sivasubramanyam A