Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/complate/complate-ssg
static-site generator for complate
https://github.com/complate/complate-ssg
Last synced: 3 days ago
JSON representation
static-site generator for complate
- Host: GitHub
- URL: https://github.com/complate/complate-ssg
- Owner: complate
- Created: 2017-06-16T14:11:36.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2019-12-11T08:32:30.000Z (about 5 years ago)
- Last Synced: 2024-12-06T11:36:44.701Z (21 days ago)
- Language: JavaScript
- Size: 27.3 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
complate-ssg
============
static-site generator for [complate](https://complate.org), creating HTML pages
from Markdown and other formats
[](https://www.npmjs.com/package/complate-ssg)
[](https://travis-ci.org/complate/complate-ssg)
[](https://greenkeeper.io)
Getting Started
---------------
```
$ npm install complate-ssg
```
```
$ complate-ssg [options] [content_directory [target_directory]]
```
(See `complate-ssh -h` for a list of options.)
Source files (see [Source Content](#source-content) below) reside in the content
directory, resulting HTML files will be created in the target directory.
The easiest way is to start from the samples (e.g. by copying
`node_modules/complate-ssg/samples`):
* complate is used to generate a views bundle for rendering HTML – typically
with [faucet-pipeline](http://faucet-pipeline.org) compiling JSX
* complate-ssg uses these views to generate HTML pages from Markdown files
Source Content
--------------
Out of the box, complate-ssg treats `.md` files as
[Markdown](http://commonmark.org/help/). For additional formats, see
[Customization](#customization) below.
Each file must contain a metadata preamble (AKA front matter) at the top,
separated by a blank line:
```markdown
title: Hello World
lorem ipsum
* foo
* bar
dolor sit amet
```
Views
-----
HTML is rendered using complate views:
```jsx
function render({ slug, metadata, html }) {
return
{safe(html)}
;
}
function DefaultLayout({ title }, ...children) {
return
{title}
{children}
;
}
```
The `render` function serves as the entry point for all pages; it might render
different layouts based on `slug`, which is passed in alongside source contents'
`metadata` and `html`.
Next we need to register that `render` function and allow complate-ssg to invoke
it via `renderView`:
```jsx
import Renderer, { createElement, safe } from "complate-stream";
let { registerView, renderView } = new Renderer();
registerView(render);
export default renderView;
```
Finally, we need to compile our JSX views to a bundle (`dist/views.js` by
default), e.g. using [faucet-pipeline](http://faucet-pipeline.org) – see the
`samples` directory for details.
Customization
-------------
Rendering of source content can be customized via the imperative API – e.g. for
additional file extensions, formats or to adjust link URIs.
Let's create a file `ssg.js`:
```javascript
let ssg = require("complate-ssg");
let markdown = require("complate-ssg/src/markdown");
// all arguments are optional; defaults are shown below
let referenceDir = __dirname;
let options = { // all entries are optional
transforms: {
md: (source, metadata) => markdown(source)
}
};
ssg(referenceDir, options);
```
The built-in Markdown module supports influencing link targets, e.g. to remove
the `.html` file extension for internal links:
```javascript
options.transforms = {
html: (source, metadata, pages) => markdown(source, {
resolveURI: uri => {
if(pages.has(uri)) {
return uri.replace(".html", "");
}
return uri;
}
})
};
```
If we want to support a different file extension, we need to add an entry to
`options.transforms`:
```javascript
options.transforms = {
txt: (source, metadata) => source
};
```
This will add support for `.txt` files in the content directory, passing
contents through unmodified. (Note that these files also require a metadata
preamble, even though it's unused here.)
We might also want to support other formats, e.g.
[AsciiDoc](https://asciidoctor.org) – in which case we'd have to find some
library to generate HTML from `.adoc` sources:
```javascript
options.transforms = {
adoc: (source, metadata) => asciidoc(source, { layout: metadata.layout })
};
```
Here's an approximation of complate-ssg's default values for reference:
```javascript
let referenceDir = process.cwd();
let options = {
content: "./content",
target: "./dist/site",
views: {
bundle: "./dist/views.js",
name: "render"
},
transforms: {
md: (source, metadata) => markdown(source, {
// if true, this activates typographic enhancements like smart
// quotes, dashes and ellipses
smart: metadata.smart,
// if true, this disallows raw HTML in Markdown sources
safe: metadata.safe
})
}
};
```