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

274 lines
6.3 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,
2 years ago
* Some more Tests
* Image Handling in Markdown
2 years ago
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 |
2 years ago
| view | {String} | page.njk | Tempate to render file |
2 years ago
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 %}
```
2 years ago
## Media
Image Files can be add to the Markdown-Structure and will be processed by [Sharp](https://sharp.pixelplumbing.com/).
```
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 add
```
---
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"
---
```
2 years ago
## 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>
```
## 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'
```