Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mikeralphson/jekylljs

JekyllJS is a Node.js replacement for Jekyll sites, allowing you to build your site, as-is, without needing to install Ruby or Python
https://github.com/mikeralphson/jekylljs

jekyll jekyll-blog jekyll-site jekyll-website jekylljs node nodejs

Last synced: 3 months ago
JSON representation

JekyllJS is a Node.js replacement for Jekyll sites, allowing you to build your site, as-is, without needing to install Ruby or Python

Awesome Lists containing this project

README 

        
# README #



JekyllJS is a Node.js replacement for Jekyll sites, allowing you to build your site, as-is, without needing to install Ruby or Python. [The story behind it](http://divillysausages.com/2016/01/24/leaving-jekyll-behind/)



## Features ##



- No need to convert your site - liquid markup is handled using [liquid-node](https://github.com/sirlantis/liquid-node)

- Near identical output (see *Differences* below)

- Can optionally serve your site (including 404 page), so you can see your changes immediately

- Bonus liquid templates for generating a tags page, an archive page, and a RSS feed (found in the *bonus/* folder)

- It's very simple, so I'm having a hard time coming up with a fifth feature



## Differences ##



- **Code highlighting**: Jekyll uses Pygments or Rouge for code highlighting, while JekyllJS uses [highlight.js](https://highlightjs.org/). Your code still gets highlighted, just the output will be different

- **Dates**: Dates in JavaScript handle [Romance Daylight Time](https://en.wikipedia.org/wiki/Central_European_Time), meaning that if you're in Europe, any dates between the end of March to the end of October will have an extra hour in the output, i.e. `new Date( "2016-04-01 00:00:00 +0100" )` will print as `Fri Apr 01 2016 01:00:00 GMT+0200 (Romance Daylight Time)`. This may or may not be a problem for you, depending on how you use dates in your site

- **Categories**: JekyllJS doesn't support them, as I don't use them in my site. If there's a need, however, that can be changed

- **Include variables**: Assigning [variables for the `{% include %}` tag](http://jekyllrb.com/docs/templates/#includes) isn't supported. If you need support for tokens (for dynamic includes), you need to apply the patch listed below

- **Null `{% if %}` checks**: If you check for null via `{% if someVar == null %}`, you'll need to change it to `{% if someVar == undefined %}` or just simply `{% if someVar %}`



## Patches ##



Liquid-node doesn't currently support tokens in the `{% include %}` tag, so if it's something you need, you can apply the quick patch fix found in *include.js* in the *patches/* directory. Just copy the file to the *node_modules/liquid-node/lib/liquid/tags/* folder after you've installed your dependencies.



When I added Markdown support using the [marked node.js library](https://github.com/chjj/marked) I found that it was escaping all quotes for all reasons, including normal text ("don't", "can't", "I'm", etc). I don't particularly like this behaviour (it's still valid HTML though), so I added a fix around it. Just replace the *marked.js* file in the *patches/* directory with the one in the *node_modules/marked/lib/* folder if you want to do the same.



## Config ##



JekyllJS comes with a [simple config](https://github.com/lorenwest/node-config) file, *config/default.json*, meaning you can change a few things without having to re-compile the project. It looks like this:



```json

{

	"log":{

		"level":"info"

	},

	"src":{

		"path":"C:/PATH/TO/WEBSITE/",

		"404":"/404/"

	},

	"meta":{

		"keywords":"default,keywords,here",

		"description":"default description"

	},

	"opengraph":{

		"fb:admins":"XXXXX",

		"og:type":"article",

		"og:image":"/img/open_graph.png"

	},

	"highlight":{

		"parentClassName":"highlight",

		"shouldWrap":true

	},

	"server":{

		"port":4000

	}

}

```



which translates as:



- `log.level`: the level used by [Bunyan](https://github.com/trentm/node-bunyan), the logger used by JekyllJS

- `src.path`: the full path to the folder containing your Jekyll site (i.e. where *_layouts/* and *_posts/* live)

- `src.404`: the path for the file to serve as the 404 page, if you have one

- `meta.keywords`: the default meta keywords to add to each page if the page doesn't specify any. Set to null or leave out to ignore this

- `meta.description`: the default meta description to add to each page if the page doesn't specify one. If null or left out, then the description in *_config.yml* will be used (if set)

- `opengraph.fb:admins`: the ID of the Facebook user that you want to associate as the admin of the page. If null, then it's not added to the page

- `opengraph.og:type`: the default type for each page, unless overwritten. If null and not overwritten, then it's not added to the page

- `opengraph.og:image`: the image to use as the default OpenGraph share. If null and not overwritten, then it's not added to the page

- `highlight.parentClassname`: the classname for the parent node for highlighted code. Use `highlight` to keep with the Jekyll generated code, or `hljs` to use the highlight.js version

- `highlight.shouldWrap`: Should we wrap our generated code in a div? Use `true` to keep with the Jekyll generated code, or `false` to use the highlight.js version (in which case the `highlight.parentClassname` will be applied to the code tag

- `server.port`: the port to use when serving the site



NOTE: other basic OpenGraph tags can be auto generated:



- `og:title`: the post title, or the site title if there isn't a post one: ``

- `og:site_name`: taken from *_config.yml*: ``

- `og:url`: the full canonical url of the page; ``



## Sample Post YAML FrontMatter ##



A quick idea of the frontmatter for a post, some of which would override the site defaults:



```yaml

---

date: 2016-04-23 17:19:00 +0100

layout: post

permalink: /intro/

title: "Intro"

meta:

  keywords: one, two, three, four

  description: This is the description for the intro doc

opengraph:

  fb:admins: 1234567

  og:type: website

  og:image: /img/open_graph2.png

  og:locale: en_GB

  og:video: "http://some_video.com"

tracking:

  fbpixel: XXXXXXXXXXXXXXX

---

```



where:



- `date`: the date the post was published

- `layout`: the layout to use for the post

- `permalink`: the permalink for the post

- `title`: the title for the post

- `meta.keywords`: keywords to use for the `` tag in the page head. If null, then the defaults from the config are used

- `meta.description`: the description to use for the `` tag in the page head. If null, then the default from the config is used

- `opengraph.fb:admins`: the ID of the Facebook user to set as the admin from the page. If null, then the default from the config is used

- `opengraph.og:type`: the type of the page for opengraph. If null, then the default from the config is used

- `opengraph.og:image`: the image to use for opengraph. If null, then the default from the config is used

- `og:locale`/`og:video`: any other opengraph tag will be added to the page automatically

- `tracking:fbpixel`: the ID of the Facebook tracking pixel that you want to add to the page



## Compiling JekyllJS ##



JekyllJS is written in [TypeScript](http://www.typescriptlang.org/), and comes with a project file for [Visual Studio Code](https://code.visualstudio.com/). You can install TypeScript using 



```npm install -g typescript```



The js files are included, so you don't need to have TypeScript in order to run JekyllJS.



## Running JekyllJS ##



To compile your site, make sure the config in *config/default.json* is up to date, then open a command line and type



```node app.js | "./node_modules/.bin/bunyan" -o short```



If you want JekyllJS to serve your site as well, use



```node app.js serve | "./node_modules/.bin/bunyan" -o short```