jekyll.js

A TypeScript reimplementation of Jekyll, the static site generator. This project aims to provide a Node.js-based alternative to the Ruby-based Jekyll that is fully compatible with existing Jekyll sites.

Features

• 🚀 CLI Tools: Build, serve, and create Jekyll sites from the command line
• 📦 Zero Dependencies on Ruby: Pure TypeScript/Node.js implementation
• 🔄 Jekyll Compatible: Works with existing Jekyll sites without modification
• 🎨 Liquid Templates: Full support for Liquid templating
• ⚡ Fast Development: Live-reload development server
• ✨ Modern Features: Optional modern JavaScript enhancements (syntax highlighting, image optimization, validation)

Installation

npm install -g jekyll-ts

Or use npx to run without installing:

npx jekyll-ts <command>

Usage

Create a New Site

Create a new Jekyll site at the specified path:

jekyll-ts new my-site
cd my-site

Create a blank site without default theme:

jekyll-ts new my-site --blank

Build Your Site

Build your site from source to destination:

jekyll-ts build

With custom options:

jekyll-ts build --source ./src --destination ./public --verbose

Available options:

• -s, --source <path> - Source directory (default: .)
• -d, --destination <path> - Destination directory (default: ./_site)
• --config <file> - Custom configuration file (default: _config.yml)
• --drafts - Process and render draft posts
• --future - Publish posts with a future date
• -w, --watch - Watch for changes and rebuild automatically
• -I, --incremental - Enable incremental build (only rebuild changed files)
• --progress / --no-progress - Show/hide progress indicators (default: enabled for TTY)
• --verbose - Print verbose output

Watch Mode: When the --watch flag is enabled, jekyll-ts will monitor your source files for changes and automatically rebuild your site when files are modified, added, or deleted. This is useful for development workflows.

Incremental Builds: When the --incremental flag is enabled, jekyll-ts will only rebuild files that have changed since the last build, significantly improving build performance for large sites. The build cache is stored in .jekyll-cache/ directory.

jekyll-ts build --incremental

Limitations of Incremental Builds

Incremental builds speed up development, but have important limitations:

1. Configuration changes require a clean build: Changes to _config.yml automatically trigger a full rebuild.
2. Data file changes may not trigger rebuilds: Changes to files in _data/ may not automatically rebuild affected pages. Run a clean build if you update data files.
3. Include file changes are not tracked: Edits to files in _includes/ may not trigger rebuilds for pages that use them.
4. Layout inheritance chains may not be fully tracked: Changes to parent layouts may not rebuild all dependent pages.
5. Static files are always copied: Files in assets/ or other static directories are copied on every build.

When in doubt, run a clean build: Use jekyll-ts build without --incremental to ensure your site is fully rebuilt.

jekyll-ts build --watch

Serve Your Site Locally

Build your site and start a development server:

jekyll-ts serve

With custom options:

jekyll-ts serve --port 3000 --host 0.0.0.0

Available options:

• -s, --source <path> - Source directory (default: .)
• -d, --destination <path> - Destination directory (default: ./_site)
• --config <file> - Custom configuration file (default: _config.yml)
• -P, --port <port> - Port to listen on (default: 4000)
• -H, --host <host> - Host to bind to (default: localhost)
• --livereload - Use LiveReload to automatically refresh browsers (default: true)
• --no-livereload - Disable LiveReload
• --drafts - Process and render draft posts
• --future - Publish posts with a future date
• --progress / --no-progress - Show/hide progress indicators (default: enabled for TTY)
• --verbose - Print verbose output

Using Themes

Jekyll.js supports npm-based themes that provide layouts, includes, assets, data files, and configuration defaults. To use a theme:

1. Install the theme package:

npm install jekyll-theme-minimal

2. Add the theme to your _config.yml:

theme: jekyll-theme-minimal

3. Build your site:

jekyll-ts build

Theme File Override:

• Site files always take precedence over theme files
• Create _layouts/default.html in your site to override the theme's default layout
• Create _includes/header.html to override the theme's header include
• Create _data/navigation.yml to override the theme's navigation data

Theme Features:

• Layouts & Includes - Template files for your site structure
• Assets - CSS, JavaScript, images, and fonts
• Data Files - Default data (navigation, authors, settings) that merges with site data
• Configuration Defaults - Theme-level _config.yml with default settings
• Metadata - Theme info from package.json (name, version, author, etc.)

Theme Structure: A theme package should have the following structure:

jekyll-theme-name/
├── _layouts/       # Layout files
├── _includes/      # Include files
├── _sass/          # Sass partials
├── _data/          # Default data files
├── assets/         # CSS, JS, images
├── _config.yml     # Theme defaults
└── package.json    # Theme metadata

📖 For detailed theme development guide, see docs/theme-development.md

Using Plugins

Jekyll.js includes several built-in plugins and supports loading custom plugins from npm packages.

Built-in Plugins:

• jekyll-seo-tag - SEO meta tags
• jekyll-sitemap - XML sitemap generation
• jekyll-feed - Atom feed generation
• jekyll-jemoji - Emoji support
• jekyll-mentions - @mention links
• jekyll-redirect-from - Redirect pages
• jekyll-avatar - GitHub avatar helper
• jekyll-github-metadata - GitHub repository metadata

Enable plugins in _config.yml:

plugins:
  - jekyll-seo-tag
  - jekyll-sitemap
  - jekyll-feed

Using npm Plugins:

Install and use custom plugins from npm:

npm install my-jekyll-plugin

plugins:
  - jekyll-seo-tag           # Built-in
  - my-jekyll-plugin         # npm plugin
  - @myorg/jekyll-plugin     # Scoped npm plugin

📖 See PLUGINS.md for detailed plugin documentation and how to create custom plugins.

Development

Setup

Clone the repository and install dependencies:

git clone https://github.com/benbalter/jekyll.js.git
cd jekyll.js
npm install

Build

Build the TypeScript source:

npm run build

Test

Run the test suite:

npm test

Benchmark

Run benchmark tests comparing Jekyll TS performance:

npm run benchmark

This runs a full integration benchmark test that:

• Builds the test fixture site using Jekyll TS via CLI
• Compares build times against Ruby Jekyll (if installed)
• Runs multiple iterations to measure consistency
• Outputs detailed performance metrics

If Ruby Jekyll is not installed, the benchmark will only measure Jekyll TS performance.

Setting up Ruby Jekyll for benchmarking

To enable side-by-side comparison with Ruby Jekyll:

1. Install Ruby (version 3.2 or higher recommended)
2. Install dependencies:

   bundle install

3. Run the benchmark:

   npm run benchmark

The Gemfile includes Jekyll 4.3 and required dependencies for running the benchmark comparison.

Lint

Lint the source code:

npm run lint
npm run lint:fix  # Auto-fix issues

Project Structure

jekyll.js/
├── src/
│   ├── cli/          # CLI command implementations
│   │   ├── commands/ # Individual command handlers (new, build, serve)
│   │   └── index.ts  # Main CLI entry point
│   ├── core/         # Core build engine
│   │   ├── Builder.ts      # Site build orchestration
│   │   ├── CacheManager.ts # Incremental build cache
│   │   ├── Document.ts     # Document representation
│   │   ├── Paginator.ts    # Pagination support
│   │   ├── Renderer.ts     # Liquid template rendering
│   │   ├── SassProcessor.ts # SASS/SCSS compilation
│   │   ├── Site.ts         # Site management
│   │   ├── StaticFile.ts   # Static file handling
│   │   ├── ThemeManager.ts # Theme loading
│   │   └── markdown.ts     # Markdown processing
│   ├── config/       # Configuration parsing
│   │   └── Config.ts # _config.yml parser and validator
│   ├── plugins/      # Built-in plugins
│   │   ├── seo-tag.ts        # SEO meta tags
│   │   ├── sitemap.ts        # Sitemap generation
│   │   ├── feed.ts           # RSS/Atom feed
│   │   ├── jemoji.ts         # Emoji support
│   │   ├── mentions.ts       # @mention links
│   │   ├── redirect-from.ts  # Redirect pages
│   │   ├── avatar.ts         # GitHub avatar helper
│   │   ├── github-metadata.ts # GitHub repository metadata
│   │   ├── html-minifier.ts  # HTML minification
│   │   ├── image-optimization.ts # Sharp-based image optimization
│   │   ├── resource-hints.ts # Resource hints (preload/prefetch)
│   │   └── syntax-highlighting.ts # Shiki-based syntax highlighting
│   ├── server/       # Development server
│   │   └── DevServer.ts
│   ├── themes/       # Theme templates
│   ├── utils/        # Utility functions
│   └── index.ts      # Library entry point
├── docs/             # Documentation
├── dist/             # Compiled JavaScript output
└── test-fixtures/    # Test Jekyll sites

Compatibility

Jekyll.js aims to be a drop-in replacement for Ruby Jekyll 4.x. Most Jekyll sites work without modification.

📖 See the docs folder for comprehensive documentation including:

• MIGRATION.md - Step-by-step migration guide from Ruby Jekyll
• FEATURES.md - Complete feature status reference
• PARITY.md - Parity details and improvements
• ROADMAP.md - Development timeline and plans
• MODERN-FEATURES.md - Modern JavaScript enhancements

Current Status (v0.1.0)

88% feature parity with Ruby Jekyll. All core features implemented:

• ✅ CLI commands, configuration, Liquid templating (60+ filters)
• ✅ Pages, posts, collections, layouts, includes, data files
• ✅ SASS/SCSS, front matter defaults, pagination, themes
• ✅ 8 built-in plugins (SEO, sitemap, feed, jemoji, mentions, redirect-from, avatar, github-metadata)
• ✅ Watch mode, incremental builds, live reload dev server

Ruby plugins are not supported - they require TypeScript reimplementation.

Note: See PLUGINS.md for plugin documentation and how to create custom plugins.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Acknowledgments

This project is inspired by and aims to be compatible with Jekyll, created by Tom Preston-Werner and maintained by the Jekyll core team.