blog-engine-sac

Blog-engine-sac

This is a static site generator, that reads your input files and outputs web pages.

Feature Overview

• Generates an index page that links to all posts
• Works without JavaScript
• Handles translations
• Create categories and filter posts based on category
• Client side, ultra fast search
• Ouput files are minified
• Make posts semi private with indexed: false
• Post sources can be txt markdown html and more
• Post sources can be any valid URL
• Fast (250 files in less than 3 seconds) and cli based
• 100% lighthouse score, WCAG 2.1 compliant
• Responsive design
• Dark mode ready

How to use ?

Set up

1. Download NodeJS 14+
2. npm i npm@latest-6 -g

Set up with the template

1. Copy template and follow instructions in its readme

Setup manually

1. Create a new project (folder)
2. Create a valid package.json file with npm init for example
3. Run the command npm i blog-engine-sac
4. add scripts inside package.json

  "scripts": {
    "sac": "node node_modules/blog-engine-sac/source/main.js inputFolder=.",
    "scaleImages": "node node_modules/blog-engine-sac/source/media/image/scaleImageCli.js"
  }

1. follow instructions below to create required files
2. npm run sac
3. npm run scaleImages
4. to view the results use a static file server

Create a new post

Create a new file in the folder source/. Suported file types:

• text (.txt)
• markdown (.md)
• html (.html)
• yaml (.yaml)
• json (.json)
• ini (.ini)
• toml (.toml)

A markdown file is a normal text file with .md file extension. The name of the file is used as the name of the post.

Simple post

Create a file in source/. For example my-post.md or my-post.txt.

Post with metadata

Create a simple post then create a meta file with the same base name. For example my-post.yaml. Meta files in the readme will be yaml, but they can be any format in the list:

• yaml
• json
• ini
• toml

title: I am about to write a title
lang: en
author: Author name
ready: true
indexed: true
creationDate: 2018/02/15
modifiedDate: 2035/02/19
tags:
  - cooking
  - sports
  - travel
translations: []
license: CC0-1.0

ready

set ready to false to not process them at all

indexed

set indexed to false, to have it in the blog, but the index.html will not have a link to it. The only way to open it would be to know the exact URL.

tags

tags is a list of categories that your post will appear in. Categories are pages that list only post of that category. For example if you have "travel" inside categories inside blog-engine-sac settings, and travel as a tag of the post, then the post will be listed on the travel category

translations

Use it to mark posts as translations of another post. If we have the following files:

• Geography.md (in English)
• Géographie.md (in French)
• Erdkunde.md (in German)

Use the following meta file to link them:

Geography.yaml

lang: en
translations:
  - lang: fr
    src: ./Géographie.md
  - lang: de
    src: ./Erdkunde.md

Each translation item may use any key value pair seen above (title, author, etc)

External post

Create a file that describes where to find the external post. For example js-style-guide.yaml . Including a post from the web: Add a yaml file in source/ with src set to the url.

js-style-guide.yaml

src: 'https://raw.githubusercontent.com/GrosSacASac/JavaScript-Set-Up/master/js/red-javascript-style-guide/readme.md'

Another Example with this readme file:

blog-engine-sac-readme.yaml

src: 'https://gitlab.com/GrosSacASac/blog-engine-z/-/raw/master/README.md'
lang: en
Content-Type: text/markdown

site settings

Create file blog-engine-sac.yaml with

defaultLang: en
defaultAuthor: AUTHOR
mainTitle: Blog
subTitle: Change title and subtitle in blog-engine-sac.yaml
defaultLicense: CC-BY-NC-4.0
htmlExtensionLinks: false
categories:
  - tag: travel
  - tag: dance

Ideally defaultLicense is a SPDX identifier.

defaultLang is a 2 letter shorthand for the language (ISO 639-1).

htmlExtensionLinks: If true, links will have the ".html" extension. Default is false.

Change the values as you see fit.

categories

categories are provided by the user as an array for the entire blog

for example: travel, cuisine, sports

Each category will have a dedicated index page that acts like the main index page but only lists post of that category. Posts will be in that category if they have a corresponding tag.

about page

Create file source/extras/about.md.

contact page

Create file source/extras/contact.md.

footer

Create file source/extras/footer.md.

Edit Images

Open folder images Replace the images with new ones but keep the exact filename to not break the links. (Images are linked from other files, not copied, the name of the files are used)

Required images

• images/about.jpg
• images/contact.jpg
• images/home.jpg
• images/post.jpg

Custom css

Add the following key-value pair in your site settings.

customCss: custom.css

Then create a folder named css. Inside create a file custom.css. Then copy inside custom.css the first 2 rules found inside blog-engine-sac.css. These are some css variables easy to edit as a starting point.

user provided tags

found in the meta file as an array

auto generated tags (disabled)

are gathered from the plain text of each post based on heuristacs (rarity and uniqueness)

tags

tags is a set that combines user provided tags and auto generated tags and title. It is used for search function. They are also displayed after the post.

What is mark down

A text format. Learn it here https://commonmark.org/help/

About the code

Don't remove, edit or add any other file unless you know exactly what you are doing!

HTML files

are generated. Do not edit directly

About

Design starting point

Start Bootstrap - Clean Blog is a stylish, responsive blog theme for Bootstrap created by Start Bootstrap. This theme features a blog homepage, about page, contact page, and an example post page along with a working PHP contact form.

Changelog

Copyright and License

CC0 (Only for blog-engine-sac itself)

Changelog

5.17.0

Add htmlExtensionLinks option. If true, links will have the ".html" extension. Default is false.