A custom built static site generator that powers https://www.sivasubramanyam.me πŸ‹οΈβ€
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
docs
lib
.eslintrc.js
.gitignore
.travis.yml
README.md
package.json
yarn.lock

README.md

Lego Build Status

A custom built static site generator that powers sivasubramanyam.me πŸ‹οΈβ€

Why?

Having written several build tools at work over the last few years, I wanted to try my hands at rolling out a full featured static site generator. I had been using Flask earlier to run several applications and I also used that to power my site. Over the years, those applications were decommissioned but the static site remained. It was getting increasingly difficult to maintain a static site on Flask and I wanted to see what all it takes to build a static site generator.

This was a great learning experience to be honest.

Tell me more

  • Built with NodeJS.
  • Supports Liquid templates.
  • Supports minification and uglification of JS and CSS file(with browserslist).
  • Does asset revision of CSS, JS and image files files.
  • JPG and PNG images under static will be optimised with imageoptim.
  • Automatic sitemap generation.
  • Supports extracting and inlining 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 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.

Directory structure

.
β”œβ”€β”€ CNAME
β”œβ”€β”€ README.md
β”œβ”€β”€ layouts
β”‚Β Β  β”œβ”€β”€ post.html             // will be used for markdown posts
β”‚Β Β  └── tag.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
  }
}
  • skipDirsInPostUrls: 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'
}
{
  collapseWhitespace: true,
  minifyJS: true,
  minifyCSS: true,
  removeComments: true
}
  • md: Pass an array of block-level custom containers that can be used by the Markdown parser. Refer markdown-it-container.
{
  md: {
    containers: [
      {
        name: 'myCustomContainer',
        options: {
          validate: function(params) {}
          render: function(tokens, idx) {}
        }
      }
    ]
  }
}
  • postCSSPlugins: An array of PostCSS plugins. These will be used in addition to cssnano and postcss-preset-env that are already included in lego.
{
  postCSSPlugins: [
    'precss',
    'postcss-nested'
  ]
}

Installation

  • Install npm and Node.
  • Run npm i -g @astronomersiva/lego.

Usage

  • Run lego g to create a new site.
  • Run lego s to run a server.
  • Run lego 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 a isDevelopment variable that you can use to disable certain stuff in development. For example, analytics.
{% unless isDevelopment %}
  <!-- analytics code -->
{% endunless %}

License

MIT Β© Sivasubramanyam A