Development

To get started developing Reptar locally:

OSX / Linux

git clone git@github.com:reptar/reptar.git
cd reptar
npm install

From there you're good to go!

Windows

First of all, if you're using Git Bash to clone the repo, then make sure that you enter this command into the terminal:

git config --global core.autocrlf false

It will ensure that all file line endings are in the LF format when cloning the repo, not the standard CRLF format that Windows uses. This is to comply with Reptar's ESLint rules.

Secondly, you might need to install some Windows build tools to make the node-gyp dependency work. This can be easily done by typing in the following into your terminal:

npm install --global --production windows-build-tools

(For more information visit this page)
If Reptar still give you errors about node-gyp after trying to install it you might need to download Python version 2 manually. During installation you need to set the PATH environment variable by clicking on a checkbox.

Finally move on to running the following commands to download Reptar and install its dependencies:

git clone git@github.com:reptar/reptar.git
cd reptar
npm install

Testing

The easiest way to add/modify/test features is by writing a test and then interacting with Reptar through there. You can start mocha in watch mode and then begin coding:

npm run test:unit -- --watch

Using development version of reptar

After you install Reptar locally you can use a debug version to quickly iterate on functionality.

The first thing you need to do is expose your local Reptar installation globally.

cd reptar
npm link

After you link Reptar you can run reptar and that will be pointing to your local installation of Reptar.

However if you make a modification to a Reptar source file you have to run npm run compile to transpile the latest code. This is a less than optimal work flow.

Instead you can also use reptar-debug as a drop in replacement for the reptar CLI tool. This file transpiles on the fly. Which allows for a workflow of editing a file and then using reptar-debug. No need for npm run compile in between.

Commit Messages

Reptar is using standard-version to standardize its commit messages. For a quick overview of what that looks like consult the quick start guide or look at previous commits.

By default a git-hook is installed to validate your commit message.

Additionally you should use commitizen to automate and streamline the process of creating properly formatted commit messages.

Cutting a release

When ready to cut a release just run npm run release. We're closely following the instructions on the standard-version documentation page.

Contributing to Reptar

Development

Refer to DEVELOPMENT.md for docs on how to develop Reptar.

Tests

Tests are ran with mocha and written with ES2015+ JavaScript.

Run tests via:

npm test

Linting

We're using eslint for linting.

Lint locally via:

npm run lint

References

Class Summary

Static Public Class Summary
public	CollectionBase
public	CollectionPage
public	Config
public	File
public	FileSystem
public	FileSystemCollection A collection that derives its content from the location of a file in the file system.
public	Metadata Handles all metadata about your site that will be accessible within every render context.
public	MetadataCollection A collection that derives its content from a match in a files yaml frontmatter data.
public	Renderer
public	Reptar
public	Server

Function Summary

Static Public Function Summary
public	ApiService(reptar: ):
public	addCollections(reptar: *)
public	async addDataFiles(reptar: *)
public	addTemplateFilter(env: Object, name: string, func: Function, async: boolean) Allow adding custom filters to the template engine.
public	async build(options: *)
public	async clean()
public	configureTemplateEngine(options: Object): Object Exposed method to configure template engine.
public	createChecksum(input: string): string Create checksum hash of input.
public	createCollection(name: , collectionConfig: , config: , renderer: ): *
public	createMarkdownEngine(options: Object): Object Create our Markdown engine.
public	fileHasFrontmatter(filePath: string): Promise<boolean> This is a fast way to check if a file has frontmatter without reading all of its contents into memory.
public	futureDatesFilter(file: File, filterConfig: Object): boolean Future date filter.
public	async init()
public	metadataFilter(file: File, filterConfig: Object): boolean Metadata filter.
public	async new(args: *)
public	parse(str: string, options: Object): JSON Parse a file with front matter.
public	parse(str: string): Object Parse a YAML string into an object.
public	prunePrivateProperties(obj: Object, isPrivate: Function): Object Given an obj it'll prune any properites that start with `_`.
public	async readDataFiles(dataPath: string): Object Load all files in the given dataPath file and parse them into a JS object.
public	renderMarkdown(md: Object, str: string): string Render a piece of string from Markdown to HTML.
public	renderTemplate(env: Object, template: string, variables: object): string Render a template with given context variables.
public	renderTemplateString(env: Object, str: string, variables: object): string Render a string template with given context variables.
public	async serve()
public	stringify(obj: Object): string Stringify an object to a YAML string.
public	stringify(str: string, data: Object): string Stringify a document.
public	async watch(options: {})

Variable Summary

Static Public Variable Summary
public	ApiPlugin: {"register": *}
public	Constants: {"ConfigFilename": string, "SourceKey": string, "DestinationKey": string}
public	Url: {"interpolatePermalink": function, "slug": function, "setSlugOptions": function, "pathHasMarkdownExtension": function, "replaceMarkdownExtension": function, "makeUrlFileSystemSafe": function, "makePretty": function, "pathFromRoot": function}
public	cache: {"setNamespace": function, "load": function, "save": function, "clear": function, "put": function, "get": function}

2.0.0 (2016-10-19)

Bug Fixes

More robust path handling for data files. (2a08f4b)
cache: Put all cache .json files in a .reptar-cache folder. (87c6b28)
coverage, tests: Fix babel-plugin-isparta from breaking e2e tests. (b3d0e4a)
file: When File is filtered do not write its content to disk. (7215ada), closes #39
plugin: Remove collection events. (5538dc0)
sort: Fix sorting Files by key and when key is a date. (2589c8c)
test: Fix e2e tests fixtures. (46976cb)
theme: Add try/catch for theme to fix e2e tests. (352e18b)

Code Refactoring

Simplify external API. (001d350)
collection: Change schema for configuring Collections. (bfb189c)
config: Remove unused 'quiet' property. (74cb0c0)

Features

config: Implement Config validation (88290fa), closes #10
Use spinners in console for better feedback. (48eb97b), closes #30
data: Support data files of .yaml or .json. (7941441), closes #32
file: Add support for setting default values on File via config. (7389309), closes #42
file: Read all files in source directory, irrespective of type. (e0ec30a)
markdown: Use markdown-it library to parse markdown. (9bdbf77), closes #34
serve: Just use Hapi as our web server. (b238130)
serve: Use server.baseurl when setting up server path. (7baed08)
template: Allow custom date formats. (6067af3)
watch: Use web server to implement more durable watch mode. (492a773), closes #43

Performance Improvements

file: Improve time it takes to check if File has frontmatter. (3e5ea36)

BREAKING CHANGES

config: You must remove the 'quiet' property from your _config.yml. It's no longer supported.
collection: This creates a more intuitive config schema when configuring a Collection. It is only a re-structuring of existing properties.
markdown: This changes the library used to parse markdown to markdown-it. This also changes the _config.yml structure when defining how the markdown parser can be customized.
file: This moves filter configurations from Collections to File. This is required as we need to know if a File should be written to disk, and Collections delegate their behavior depending on how the File is configured. This is an easy transition, mostly moving the filter configuration from the Collection to File under the filters key.
plugin: Due to internal re-organizations there are no more collection before/after write events.
This changes the external API and makes it simpler. Now there's only new Yarn(), yarn.update() and yarn.build(). That's all that's needed to build your Yarn site.
file: We've removed a StaticCollection. You no longer need to specify every static file you have in your source directory, Yarn will now check every file in your source directory and check if it has frontmatter to decide whether it should process and copy the file, or just copy the file. This lets you put any file in your source directory and have it be automatically seen by Yarn and copied over.
file: This now changes where a File gets its template and permalink values from. Before a File inherited those values from the Collection in which it belonged. Now it's set directly on the File, either via its own frontmatter or from the defaults in the config.