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.
301 lines
7.1 KiB
301 lines
7.1 KiB
# 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](https://www.pexels.com/creative-commons-images/).
|
|
|
|
## 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:
|
|
|
|
```
|
|
@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](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 to add multiple Sizes. For more, check [Sharp](https://sharp.pixelplumbing.com/).
|
|
|
|
```
|
|
---
|
|
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/](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'
|
|
```
|