Generating a Website as Html-Files from a Markdown File Structure
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
Go to file
HerrHase c39f361697
adding
1 year ago
ressources adding 2 years ago
src adding 1 year ago
test adding #20 #19 #17 1 year ago
.gitignore adding 2 years ago
README.md adding 2 years ago
index.js adding 2 years ago
package-lock.json adding 2 years ago
package.json adding 1 year ago

README.md

Site-O-Mat - Core

Generating a Website as Html-Files from a Markdown-File Structure.

Why? The Main reason i had to update some Websites, but realize there were no benefit to use a Full CMS or Headless CMS like Directus. Rendering the same pages that a rarely updated seems like a waste of energy. Why not generate from a hierarchical file structure. Luckily i i had development a CMS, a few years ago, that runs on Markdown Files it had been never finished, it was only a proof of concept. But now it works for created a entire Website.

Roadmap

Next will be,

  • Some more Tests

Maybe later,

  • Integrate Eta.js and LiquidJS
  • Hooks for handle generic content

Images for Tests

No Dogs were harmed during the Tests, all Images are under cc0 and from pexels.com.

Additional Packages

@site-o-mat/webpack-plugin - Wrapper for Core to use as Webpack Plugin
@site-o-mat/query - Query for Filter, OrderBy and Reduce Data
@site-o-mat/api - Api for getting Data from JSON
@site-o-mat/blog - Example for Blog

Installation

Setup this registry in your project .npmrc file:

@site-o-mat:registry=https://gitea.node001.net/api/packages/site-o-mat/npm/

or run

npm config set @site-o-mat:registry=https://gitea.node001.net/api/packages/site-o-mat/npm/

Install with npm or yarn

npm i --save-dev @site-o-mat/core
yarn add --dev @site-o-mat/core

Configuration

Basic Usage:

const Siteomat = require('@site-o-mat/core')

const siteomat = new Siteomat(<source>, <destination>, {
    <options>
})

Name Type Default Description
destination {String} null If not set, it will use the public path
htmlMinify {Boolean} true Minify Html and remove all Whitespace

Pages

Pages are Markdown-Files, they are separates in two parts. First part is a yaml-Section,

---
title: "health goth DIY tattooed"
view: "home.njk"
meta:
    description: "La"
media:
    teaser:
        src: "_images/test.jpeg"
        alt: "cold-pressed"
---

The yaml-Section will be parsed as an Object and available in the Templates. The second part of the File will be parsed as Markdown, but it could be also empty.

After parsing Markdown-Files a Page always this values,

Name Type Default Description
path {String} / Full path with File
permalink {String} -1 Full path without Extensions, index.html will be empty
filename {String} null Name of File
hidden {Boolean} false If hidden, file will not be written
blocks {Object} Object Blocks of Directory
content {String} empty Parsed Markdown
view {String} page.njk Tempate to render file

Nesting

A Page can be a single Markdown-File, or a Directory with a index-File inside. The Name of a file or a directory will the name of the html-File. To create Sub-pages, create Sub-directories.

This Structure,

index.md
about-me.md
blog
└ index.md
  belly-polaroid-subway.md

will be,

index.html
about-me.html
blog.html
blog/belly-polaroid-subway.html

Blocks

Each Page can have Blocks. Blocks are like Pages, but they are only accessible for a single Page. To add Blocks to a page, add a "_blocks"-Directory to the Directory of the Page.

Markdown-Files in a "_blocks"-Directory will be automatic accessible for a Page. The yaml-Section is Optional.

recipes
└ index.md
  _blocks
  └ hero-1.md
    hero-2.md
    hero-3.md

Blocks will be Grouped by there name, and sorted by the number at the end. The "hero"-Files can be used like this,

{% hero in page.blocks.hero %}
    {{ hero.content }}
{% endFor %}

Media

Image Files can be add to the Markdown-Structure and will be processed by Sharp.

recipes
└ index.md
  _images
  └ dog.jpg

In Fields all keys with "src" will be handled as Path to Images. Files will be search first in current Directory of page, if nothing found, it will be search in Root-Directory of Markdown-Structure. Blocks can also have there own Images.

---
title: "health goth DIY tattooed"
view: "home.njk"
meta:
    description: "La"
media:
    teaser:
        src: "_images/dog.jpg"
        alt: "cold-pressed"
---

It is also possible to add multiple Sizes. For more, check Sharp.

---
title: "health goth DIY tattooed"
view: "home.njk"
meta:
    description: "La"
media:
    teaser:
        src:
            src: '_images/dog.jpg'
            sizes: 
                - width: 300
                - width: 500
                  height: 100
        alt: "cold-pressed"
---

Options from Sharp can be add on two different ways. As "options" for all Sizes or you can simply add options to a sizes, that means the main options will be ignored.

---
title: "health goth DIY tattooed"
view: "home.njk"
meta:
    description: "La"
media:
    teaser:
        src:
            src: '_images/dog.jpg'
            sizes: 
                - width: 300
                - width: 500
                  height: 100
                  position: 'left'
        alt: "cold-pressed"
        options:
            position: 'right'
---

Queries

Queries can be used in Templates to get Pages.

Pages

Basic Usage:

pageQuery.find()

or with options,

Name Type Default Description
parent {String} / Directory for start query
deep {Integer} -1 Deep of Recursive
orderBy {Array} null Name of field sorting, a "-" in front of the. Nested fields are also possible.
limit {Integer} null Limit results
filter {Object} null Filtering results by Fields in yaml

Filter

Basic Usage:

{
    <fieldname>: {
        <operator>: <value>
    }
}
Name Description
_eq Equal Value

Sitemap

Sitemap will be generating by Pages. Pages will be only add to Sitemap, if the have meta-robots is set to "index". Pages default is "index".

Templates

At this Time only https://mozilla.github.io/nunjucks/ is used for Templating.

Nunjunks

Functions

asset(path)

This function handle manifest-File from https://laravel-mix.com/.

<script src="{{ asset('js/app.js') }}"></script>

Json

Results from PageQuery can also be created as json-File. The can use with a simple API https://gitea.node001.net/site-o-mat/api. Create a File "json.yml" and add options.

Basic Usage:

posts:
    orderBy:
        - '-date_published'
    filter:
        view:
            _eq: 'post.njk'