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.
core/README.md

245 lines
5.8 KiB

2 years ago
# 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 Tests
* Standalone, handle Webpack only as wrapper
Maybe later,
* Integrate Eta.js and LiquidJS
* Hooks for handle generic content
## Additional Packages
[@site-o-mat/webpack-plugin](https://gitea.node001.net/site-o-mat/webpack-plugin) - Wrapper for Core to use as Webpack Plugin
[@site-o-mat/query](https://gitea.node001.net/site-o-mat/query) - Query for Filter, OrderBy and Reduce Data
[@site-o-mat/api](https://gitea.node001.net/site-o-mat/api) - Api for getting Data from JSON
[@site-o-mat/blog](https://gitea.node001.net/site-o-mat/blog) - Example for Blog
## Installation
Setup this registry in your project .npmrc file:
```
2 years ago
@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/
2 years ago
```
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')
2 years ago
const siteomat = new Siteomat(<source>, <destination>, {
2 years ago
<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.
2 years ago
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 |
2 years ago
## 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 %}
```
## 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/](Nunjunks) is used for Templating.
### Nunjunks
#### Functions
##### asset(path)
This function handle manifest-File from [https://laravel-mix.com/](Laravel-Mix).
```
<script src="{{ asset('js/app.js') }}"></script>
```
#### Filters
##### resize
2 years ago
The Filter is using [sharp](https://github.com/lovell/sharp), for crop, resize and
2 years ago
optimize Images. The Filter needs a relative Path in the File Structure.
Basic Usage:
```
{% page.teaser.src | resize({ 'width': '300' }) %}
```
Add options:
```
{% page.teaser.src | resize({ 'width': '300' }, { sigma: 2 }) %}
```
## 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](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'
```