Permalink
Fetching contributors…
Cannot retrieve contributors at this time
386 lines (268 sloc) 8.57 KB
description icon layout title weight
Configuration options for electric-cli tasks.
gear
docs
Configuration
5

electric.config.js

All options can be set in the electric.config.js file located in the root of your project. This file must export an Object, or a function that returns an Object.

module.exports = {
	pathDest: 'build'
};

// or

module.exports = function() {
	return {
		pathDest: 'build'
	};
};

Options

basePath

  • Type: String
  • Default: ''

Prefixes all urls used in resources and navigation elements with the supplied path.

Example:

module.exports = {
	basePath: '/base-path'
};

Now all of the generated navigation elements will be prefixed with this path.

<a class="sidebar-link" href="/base-path/docs/index.html"><span>Pages</span></a>

It will also prefix the urls the auto-generated script and link tags.

<link rel="stylesheet" href="/base-path/vendor/senna/senna.css">

This setting can be useful for hosting services such as gh-pages which nest your project under a path generated by your project name. For example, https://electricjs.github.io/project-name/ would require the following config.

module.exports = {
	basePath: '/project-name',
	deployOptions: {
		branch: 'gh-pages'
	}
};

codeMirrorLanguages

  • Type: Array<languageName>
  • Default: ['xml', 'css', 'javascript']

An Array of langauge names for syntax highlighting. See CodeMirror for a list of available languages.

codeMirrorTheme

  • Type: String
  • Default: 'dracula'

Theme to be used by CodeMirror. See CodeMirror for a list of available themes.

deployOptions

  • Type: Object
  • Default: {lb} branch: 'wedeploy' {rb}

Configuration options used by the deploy command. See gh-pages for further configuration options.

envOptions

  • Type: Object

Allows you to set predefined options that can conditionally overwrite the default options from electric.config.js.

Example:

Let's say you need to deploy to two different branches, envOptions allows you to define a custom set of options that can be enabled via a command line flag.

module.exports = {
	envOptions: {
		ghpages: {
			deployOptions: {
				branch: 'ghpages'
			}
		}
	},
	deployOptions: {
		branch: 'default-branch'
	}
};

Running electric deploy will use the default settings, publishing to the default-branch.

However, if you run the following,

electric deploy --env ghpages

The ghpages options defined above will overwrite the default options, deploying your site to the gh-pages branch.

Note: any of the configuration options can be set in envOptions, not just what is seen in the example.

frontMatterHook

  • Type: function

Allows modifications of your project's front-matter before it's passed to the templates.

Example:

module.exports = {
	frontMatterHook: function(data) {
		data.someValue = 'Hello, World!';

		return data;
	}
};

In this example the property someValue will be accessible via the $site parameter in your pages/templates.

---
description: "Page description."
layout: "docs"
title: "Page"
---

{$site.someValue}

markdownOptions

  • Type: Object

An Object Literal containing configuration options for Remarkable which is used to render Markdown files.

Example:

module.exports = {
	markdownOptions: {
		breaks: true
	}
};

See Remarkable's documentation for list of options.

markdownRenderer

  • Type: function|Remarkable

Allows complete customization over the markdown renderer. Value can either be instance of Remarkable or a function which receives the default instance of Remarkable as an argument.

Example:

// New Remarkable instance
module.exports = {
	markdownRenderer: new Remarkable()
};

// Function
module.exports = {
	markdownRenderer: function(md) {
		md.core.ruler.enable([
			'abbr'
		]);

		return md;
	}
};

pathDest

  • Type: String
  • Default: dist

The path that generated files are placed in.

Example:

module.exports = {
	pathDest: 'build'
};

Now all generated files will be placed in the build directory.

pathSrc

  • Type: String
  • Default: src

The path where all source files are located.

Example:

module.exports = {
	pathSrc: 'web'
};

Now electric will look inside the web directory for all source files.

metalComponents

  • Type: Array<String>

Array of npm modules that expose Metal components. These also must be added as npm dependencies in your package.json.

Example:

module.exports = {
	metalComponents: ['electric-components']
};

The components found in the electric-components package will now be available to all soy files in your project.

Note that every package listed in metalComponents must also be listed as a dependency in the project's package.json.

sassOptions

  • Type: Object

Config object passed to gulp-sass.

Example:

module.exports = {
	sassOptions: {
		includePaths: ['node_modules/some-package/scss']
	}
};

staticSrc

  • Type: Array<String>

Array of glob patterns for static files found in the options.pathSrc directory. These glob patterns target anything that isn't part of the build system (pages, layouts, styles, etc.).

Note: it is not recommended to overwrite this property.

uglifyBundle

  • Type: boolean
  • Default: false

Determines if bundle files are both minified and uglified.

When using electric-cli, this option defaults to true during the deploy task, and defaults to false during all others.

Warning: enabling this option can significantly increase build times.

vendorSrc

  • Type: Array<String>
  • Default: []

Array of glob patterns for .css and .js files that should be included in the <head> of your project.

Example:

module.exports = {
	vendorSrc: ['node_modules/some-project/src/min.js']
};

apiConfig

  • Type: Object

Configuration object to generate the API documentation following the JSDOC specification.

Example:

module.exports = {
	apiConfig: {
		layout: 'main',
		project: {
			docsConfig: {
				shallow: true,
			},
			refs: ['electric@3.0.2'],
			repo: 'electric',
			soyAPIEntitiesPath: '../../../partials/ElectricAPIEntities.soy.js',
			src: [
				'packages/electric/lib/**/*.js',
			],
			srcPath: 'packages',
			user: 'electricjs'
		}
	}
}

Parameters

  • layout ?String Set the name of your layout that Electric should take as a basis, See an example. (default main)

  • project !Object project

    • docsConfig ?Object Config object passed to documentation. default access: ['public', 'private', 'protected', 'undefined'], private: true

    • refs !Array<string> Set the tag of the version that your project was launched, example v1.0.0. (Remember that this is referring to releases released by the Github platform.)

    • repo !String Set the name of the repository that contains your project.

    • soyAPIEntitiesPath ?String Set your soy path containing APIEntitiesName.soy.js, See an example marble (default electric-marble-components/lib/ElectricAPIEntities.soy.js)

    • src !Array<string> Pass the location of the files you want the Electric to analyze and generate the documents. (glob is supported.)

    • srcPath ?String Set the source path of your project. (default src)

    • user !String Set the username or organization that your repo is on. (example electric)

apiConfig.project.soyAPIEntitiesPath has its default value will be deprecated and removed in the next major releases. See issue.