<commit_before># Wikic

[![Build Status][build-badge]][build]
[![Coveralls][coverage-badge]][coverage]
[![MIT License][license-badge]][license]
[![version][version-badge]][package]
[![Node][node-badge]][node]

a simple static site generator

## Example

- [dgeibi/note](https://github.com/dgeibi/note)

## Usage

``` javascript
const htmlclean = require('htmlclean')
const Wikic = require('wikic')

const wikic = new Wikic()

// add plugin to minify html before write
wikic.beforeWrite(function minify(context) {
  if (!context.data) return context
  const html = htmlclean(context.data)
  return Object.assign({}, context, { data: html })
})

// build the site and start watcher and server to debug or preview
wikic.build().then(() => wikic.watch().serve())
```

## Getting started

### Installation

``` bash
npm install --save wikic

#or

yarn add wikic
```

### Plugins

A plugin is a `Function`, which receives a `context` (Object) and returns a `context`. If a plugin is invoked, `this` in it may point to `wikic`. The context returned by a plugin will be passed to next plugin.

A `context` passed to a plugin is an Object which contains some of the following properties:

- src: string, absolute path of source
- dist: string, absolute path of destination
- data: string, content of document
- site: Object, site config
- page: Object, page config
- renderContext: Object, nunjucks render context, contains [`variables in layouts`](#variables-in-layouts)
- IS_DOC: Boolean, whether in docsPath

Add a plugin by passing it to [`wikic.beforeWrite`](#wikicbeforewriteplugin) or [`wikic.afterRead`](#wikicafterreadplugin).

### Configuration and Front Matter

[Default Config](lib/defaultConfig.yml)

You can create `_config.yml`(s) to override defaultConfig.

Here is an inheritance chain of configuration:

- 'defaultConfig',  `_config.yml` (in `wikic.cwd`) => `wikic.config`
- `wikic.config`, `_config.yml` (subdirectory of `wikic.cwd`, closest to markdown file) => `context.site`
- `context.page`, `context.site.page`, Front Matter in markdown => `context.page`

The `_config.yml` in `wikic.cwd` will be loaded as `wikic.config`.

The `_config.yml` closest to markdown will be merged into `context.site` (global config which is passed to plugins).

Front Matter in each markdown will be merged into `context.page` (page config which is passed to plugins) respectively.

Front Matter example:

``` yaml
---
title: Hello World # title of the page
toc: false # disable toc for this page
layout: docs # set layout for this page
hide: true # hide this page from docs list(only necessary for the file in docsPath)
---
```

### Layouts

You can create [Nunjucks](https://mozilla.github.io/nunjucks/templating.html) templates (extname is `.njk`) in `layoutPath` and set `page.layout` or `layout` in front matter to template's filename.

#### Variables in Layouts

- `site`, Object, reference to `context.site`
- `page`, Object, reference to `context.page`
    - `page.types`, Array, markdown's dirnames
- `content`, string, content of HTML built from markdown

For markdown in 'docsPath'

- `list`, string, list of documents in `docsPath`, See also [wikic.setListTemplate](#wikicsetlisttemplateopts)

#### Builtin Filter

- `typeMap`: see [`wikic.typeMap(key)`](#wikictypemapkey)
- `baseurl`: see [`wikic.getURL(url)`](#wikicgeturlurl)
- `typeMaps`: Receives a Array, Returns `array.map(typeMap)`. Tips: get typeNames array `{{ page.types | typeMaps }}`

#### Nunjucks in Markdown

Only variable `site` and `page` is available.

`{{`, `}}`, `{#`, `#}`, `{%`, `%}` in raw blocks and `<code>` blocks can be escaped.

``` html<commit_msg>docs(README): typo<commit_after># Wikic

[![Build Status][build-badge]][build]
[![Coveralls][coverage-badge]][coverage]
[![MIT License][license-badge]][license]
[![version][version-badge]][package]
[![Node][node-badge]][node]

a simple static site generator

## Example

- [dgeibi/note](https://github.com/dgeibi/note)

## Usage

``` javascript
const htmlclean = require('htmlclean')
const Wikic = require('wikic')

const wikic = new Wikic()

// add plugin to minify html before write
wikic.beforeWrite(function minify(context) {
  if (!context.data) return context
  const html = htmlclean(context.data)
  return Object.assign({}, context, { data: html })
})

// build the site and start watcher and server to debug or preview
wikic.build().then(() => wikic.watch().serve())
```

## Getting started

### Installation

``` bash
npm install --save wikic

#or

yarn add wikic
```

### Plugins

A plugin is a `Function`, which receives a `context` (Object) and returns a `context`. If a plugin is invoked, `this` in it may point to `wikic`. The context returned by a plugin will be passed to next plugin.

A `context` passed to a plugin is an Object which contains some of the following properties:

- src: string, absolute path of source
- dist: string, absolute path of destination
- data: string, content of document
- site: Object, site config
- page: Object, page config
- renderContext: Object, nunjucks render context, contains [`variables in layouts`](#variables-in-layouts)
- IS_DOC: boolean, whether in docsPath

Add a plugin by passing it to [`wikic.beforeWrite`](#wikicbeforewriteplugin) or [`wikic.afterRead`](#wikicafterreadplugin).

### Configuration and Front Matter

[Default Config](lib/defaultConfig.yml)

You can create `_config.yml`(s) to override defaultConfig.

Here is an inheritance chain of configuration:

- 'defaultConfig',  `_config.yml` (in `wikic.cwd`) => `wikic.config`
- `wikic.config`, `_config.yml` (subdirectory of `wikic.cwd`, closest to markdown file) => `context.site`
- `context.page`, `context.site.page`, Front Matter in markdown => `context.page`

The `_config.yml` in `wikic.cwd` will be loaded as `wikic.config`.

The `_config.yml` closest to markdown will be merged into `context.site` (global config which is passed to plugins).

Front Matter in each markdown will be merged into `context.page` (page config which is passed to plugins) respectively.

Front Matter example:

``` yaml
---
title: Hello World # title of the page
toc: false # disable toc for this page
layout: docs # set layout for this page
hide: true # hide this page from docs list(only necessary for the file in docsPath)
---
```

### Layouts

You can create [Nunjucks](https://mozilla.github.io/nunjucks/templating.html) templates (extname is `.njk`) in `layoutPath` and set `page.layout` or `layout` in front matter to template's filename.

#### Variables in Layouts

- `site`, Object, reference to `context.site`
- `page`, Object, reference to `context.page`
    - `page.types`, Array, markdown's dirnames
- `content`, string, content of HTML built from markdown

For markdown in 'docsPath'

- `list`, string, list of documents in `docsPath`, See also [`wikic.setListTemplate(opts)`](#wikicsetlisttemplateopts)

#### Builtin Filter

- `typeMap`: see [`wikic.typeMap(key)`](#wikictypemapkey)
- `baseurl`: see [`wikic.getURL(url)`](#wikicgeturlurl)
- `typeMaps`: Receives a Array, Returns `array.map(typeMap)`. Tips: get typeNames array `{{ page.types | typeMaps }}`

#### Nunjucks in Markdown

Only variable `site` and `page` is available.

`{{`, `}}`, `{#`, `#}`, `{%`, `%}` in raw blocks and `<code>` blocks can be escaped.

``` html
{'fraction_non_alphanumeric': 0.14073870657696005, 'fraction_numerical': 0.0, 'mean_word_length': 4.8272, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 13, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1932856', 'n_tokens_mistral': 2357, 'n_tokens_neox': 2260, 'n_words': 810}