<commit_before>extends ../../../common/templates/layout/base

include ../../templates/mixins/docsnav

block intro
	.page-header
		.container
			h1 Configuration
			p.lead How to roll KeystoneJS the way you want it.

block content
	.container: .row
		
		.col-sm-3
			+docsnav(docssection)
		
		.col-sm-9: .docs-content
			
			h2 Keystone Options
			
			a(name='options-concepts')
			h3 Setting Options
			
			p The options for KeystoneJS cover a range of behaviours, from how the express app is configured to enabling features and authentication options for integrated services.
			
			p There are three ways to set options:
			
			ul.options
				li Passing a <code>{ key: 'value' }</code> configuration <code class="data-type">Object</code> to the <code>keystone.init(options)</code> method
				li Calling <code>keystone.set('key', 'value')</code>
				li Setting environment variables in <code>process.env</code>. Only some options support this (noted below).
			
			p If you want to keep secret keys and configuration out of your codebase (especially important for open source projects, or projects where not all developers should have access to production config settings) the <a href="https://npmjs.org/package/dotenv" target="_blank">dotenv</a> module makes this very easy to manage.
			
			a(name='options-project')
			h3 Project Options
			
			p The following options control the branding, navigation and default export settings of the KeystoneJS application in the Admin UI:
			
			table.table
				col(width=210)
				col
				tr
					td <code>name</code> <code class="data-type">String</code>
					td The name of the KeystoneJS application
				tr
					td <code>brand</code> <code class="data-type">String</code>
					td Displayed in the top left hand corner of the Admin UI
				tr
					td <code>module root</code> <code class="data-type">String</code>
					td
						p This setting tells Keystone the root path of your app. By default, <code>module root</code> points to the path of the first script that required Keystone within your app. This default may be undesireable at times.
						p Setting <code>module root</code> allows you to specify a custom root path for your app. Overriding the default <code>module root</code> may be useful, for example, when unit testing your app.
						p <code>module root</code> is used by Keystone's <code>.getPath()</code> method to resolve/expand the paths of the <code>views</code>, <code>favicon</code>, <code>extensions</code>, <code>ssl cert</code>, <code>ssl key</code>, <code>ssl ca</code>, <code>emails</code>, and <code>updates</code> settings.
						p When setting a custom <code>module root</code> you may use either an absolute or a relative path.
						p.note If a relative path is used, it will be considered relative to the location of the script from which the setting was made.
				tr
					td <code>frame guard</code> <code class="data-type">String/Boolean</code>
					td
						p This settings tells Keystone how to handle <code>iframe</code> tags. It does this by setting the response <code>X-Frame-Options</code> header. This header is used to protect against "ClickJacking" attacks.
						p The default setting is <code>sameorigin</code>.
						p Valid options are:
						ul
							li <code class="default-value">"sameorigin"</code> allows requests from <code>iframe</code> tags that originate from the same server
							li <code class="default-value">"deny"</code> denies requests form all <code>iframe</code> tags, regardless of origin
							li <code class="default-value">true</code> (same as <code class="default-value">"deny"</code> )
							li <code class="default-value">false</code> disables <code>frame guard</code>
				tr
					td <code>nav</code> <code class="data-type">Object</code>
					td
						p An object that specifies the navigation structure for the Admin UI. Create a key for each section that should be visible in the primary navigation. Each key's value can be a single list path (as is seen in the URL when you view a list) or an array of list paths. When an array is used, secondary navigation is rendered in the Admin UI.
						p The nav is also used to generate the links on the Admin UI home page; any lists that are registered but not included in the <code>nav</code> will be grouped at the bottom of the screen under the 'Other' heading.
				tr
					td <code>csv field delimiter</code> <code class="data-type">String</code>
					td Allow you to choose a custom field delimiter to be used for CSV export instead of the default comma.
				tr
					td <code>app</code> <code class="data-type">Object</code>
					td Instance of Express to be used instead of the default instance.
				tr
					td <code>mongoose</code> <code class="data-type">Object</code>
					td Instance of Mongoose to be used instead of the default instance.

			p.note The <code>app</code> and <code>mongoose</code> options replace the functionality of the <code>keystone.connect()</code> method which is now deprecated.  Due to changes in Express 4, `keystone.connect()` no longer works as expected.
				
			.code-header
				h4 Custom Navigation Example
				p If you had <code>User</code>, <code>Post</code> and <code>PostCategory</code> models, you could group the posts and post categories into a <strong>Content</strong> navigation item like this:
			pre: code.language-javascript
				| keystone.set('nav', {
				|     'users': 'users',
				|     'content': ['posts', 'post-categories']
				| });
		
			a(name='options-server')
			h3 Web Server Options
			
			p The following options control the configuration of your web server and the express app:
			
			table.table
				col(width=210)
				col
				tr
					td <code>env</code> <code class="data-type">String</code>
					td
						p The environment setting to use. The keys <strong>development</strong> and <strong>production</strong> are supported, and this will have an impact on things like caching compiled templates. Defaults to <code class="default-value">process.env.NODE_ENV || "development"</code>.
						p You should really <strong>set this to <code class="default-value">production</code> for your production servers</strong> using the <code>NODE_ENV</code> environment variable. Several other modules expect this convention also.
				tr
					td <code>port</code> <code class="data-type">Number</code>
					td
						p The port to listen for request on. Defaults to <code class="default-value">process.env.PORT || 3000</code>
				tr
					td <code>host</code> <code class="data-type">String</code>
					td
						p The ip address to listen for request on. Defaults to <code class="default-value">process.env.IP || '127.0.0.1'</code>
						p <code>port</code> must be set (either by option or env variable) or the <code>host</code> option will be ignored.
				tr
					td <code>views</code> <code class="data-type">String</code>
					td
						p The path to your application's <strong>view templates</strong>. This is required for using the <code>keystone.View</code> Class, and will also be set on the express app.
						p If you're following the <a href="/guide#start_structure">recommended project structure</a>, this should be set to <code class="default-value">"/templates/views"</code>.
				tr
					td <code>view engine</code> <code class="data-type">String</code>
					td
						p The template engine to use by default. Any engine with express support should work. <strong>Jade</strong> is included with Keystone, but you will have to add any alternate engine to your project's dependencies in your <code>package.json</code>.
						p This option is set on the express app (<a href="http://expressjs.com/api.html#app.engine" target="_blank">see docs here</a>).
				tr
					td <code>custom engine</code> <code class="data-type">Function</code>
					td
						p If you want to use a custom template engine, set this option to the function that should be used to process your templates.
						p See below for an example of how to use the <a href="http://paularmstrong.github.io/swig/" target="_blank">Swig</a> template engine.
				tr
					td <code>view cache</code> <code class="data-type">Boolean</code>
					td
						p This option is passed through to Express, and controls whether compiled view templates are cached between requests.
						p It defaults to <code class="default-value">true</code> in production, or <code class="default-value">false</code> otherwise so there is rarely any reason to set it explicitly.
				tr
					td <code>locals</code> <code class="data-type">Object</code>
					td
						p The default local variables to pass to your view templates.
						p Routes can extend or change local variables by modifying <code>res.locals</code>.
				tr
					td <code>static</code> <code class="data-type">String</code> or <code class="data-type">Array</code>
					td
						p One or more paths to your application's static files. Setting this will include the <code>express.static</code> middleware.
						p If you're following the <a href="/guide#start_structure">recommended project structure</a>, this should be set to <code class="default-value">'public'</code>.
				tr
					td <code>static options</code> <code class="data-type">Object</code>
					td
						p Optional config options that will be passed to the <code>express.static</code> middleware.
				tr
					td <code>less</code> <code class="data-type">String</code> or <code class="data-type">Array</code>
					td
						p If you want Keystone to automatically compile <strong>.less</strong> files into <strong>.css</strong> files, set this value to the same path as the <code>static</code> option.
						p When this option is set, any requests to a <strong>.css</strong> or <strong>.min.css</strong> file will first check for a <strong>.less</strong> file with the same name, and if one is found, the css file will be generated.
				tr
					td <code>less options</code> <code class="data-type">Object</code>
					td
						p Optional config options that will be passed to the <code>less</code> middleware; see <a href="https://github.com/emberfeather/less.js-middleware" target="_blank">github.com/emberfeather/less.js-middleware</a> for more information.
				tr
					td <code>sass</code> <code class="data-type">String</code> or <code class="data-type">Array</code>
					td
						p If you want Keystone to automatically compile <strong>.sass</strong> files into <strong>.css</strong> files, set this value to the same path as the <code>static</code> option.
						p When this option is set, any requests to a <strong>.css</strong> or <strong>.min.css</strong> file will first check for a <strong>.sass</strong> file with the same name, and if one is found, the css file will be generated.
						p.note Note that enabling this option requires you to have specified the <a href="https://github.com/sass/node-sass" target="_blank"><code>node-sass</code></a> package as a dependency in your project's <code>package.json</code> file; it is not automatically included with Keystone.
				tr
					td <code>sass options</code> <code class="data-type">Object</code>
					td
						p Optional config options that will be passed to the <code>sass</code> middleware; see <a href="https://github.com/sass/node-sass#options" target="_blank">github.com/sass/node-sass</a> for more information.
				tr
					td <code>favicon</code> <code class="data-type">String</code>
					td
						p The path to your application's <strong>favicon</strong>. Setting this will include the <code>serve-favicon</code> middleware. Should be relative to your project's root.
						p If you're following the <a href="/guide#start_structure">recommended project structure</a>, this should be set to <code class="default-value">"/public/favicon.ico"</code>.<commit_msg>docs: update `static` and `static options` setting documentation<commit_after>extends ../../../common/templates/layout/base

include ../../templates/mixins/docsnav

block intro
	.page-header
		.container
			h1 Configuration
			p.lead How to roll KeystoneJS the way you want it.

block content
	.container: .row
		
		.col-sm-3
			+docsnav(docssection)
		
		.col-sm-9: .docs-content
			
			h2 Keystone Options
			
			a(name='options-concepts')
			h3 Setting Options
			
			p The options for KeystoneJS cover a range of behaviours, from how the express app is configured to enabling features and authentication options for integrated services.
			
			p There are three ways to set options:
			
			ul.options
				li Passing a <code>{ key: 'value' }</code> configuration <code class="data-type">Object</code> to the <code>keystone.init(options)</code> method
				li Calling <code>keystone.set('key', 'value')</code>
				li Setting environment variables in <code>process.env</code>. Only some options support this (noted below).
			
			p If you want to keep secret keys and configuration out of your codebase (especially important for open source projects, or projects where not all developers should have access to production config settings) the <a href="https://npmjs.org/package/dotenv" target="_blank">dotenv</a> module makes this very easy to manage.
			
			a(name='options-project')
			h3 Project Options
			
			p The following options control the branding, navigation and default export settings of the KeystoneJS application in the Admin UI:
			
			table.table
				col(width=210)
				col
				tr
					td <code>name</code> <code class="data-type">String</code>
					td The name of the KeystoneJS application
				tr
					td <code>brand</code> <code class="data-type">String</code>
					td Displayed in the top left hand corner of the Admin UI
				tr
					td <code>module root</code> <code class="data-type">String</code>
					td
						p This setting tells Keystone the root path of your app. By default, <code>module root</code> points to the path of the first script that required Keystone within your app. This default may be undesireable at times.
						p Setting <code>module root</code> allows you to specify a custom root path for your app. Overriding the default <code>module root</code> may be useful, for example, when unit testing your app.
						p <code>module root</code> is used by Keystone's <code>.getPath()</code> method to resolve/expand the paths of the <code>views</code>, <code>favicon</code>, <code>extensions</code>, <code>ssl cert</code>, <code>ssl key</code>, <code>ssl ca</code>, <code>emails</code>, and <code>updates</code> settings.
						p When setting a custom <code>module root</code> you may use either an absolute or a relative path.
						p.note If a relative path is used, it will be considered relative to the location of the script from which the setting was made.
				tr
					td <code>frame guard</code> <code class="data-type">String/Boolean</code>
					td
						p This settings tells Keystone how to handle <code>iframe</code> tags. It does this by setting the response <code>X-Frame-Options</code> header. This header is used to protect against "ClickJacking" attacks.
						p The default setting is <code>sameorigin</code>.
						p Valid options are:
						ul
							li <code class="default-value">"sameorigin"</code> allows requests from <code>iframe</code> tags that originate from the same server
							li <code class="default-value">"deny"</code> denies requests form all <code>iframe</code> tags, regardless of origin
							li <code class="default-value">true</code> (same as <code class="default-value">"deny"</code> )
							li <code class="default-value">false</code> disables <code>frame guard</code>
				tr
					td <code>nav</code> <code class="data-type">Object</code>
					td
						p An object that specifies the navigation structure for the Admin UI. Create a key for each section that should be visible in the primary navigation. Each key's value can be a single list path (as is seen in the URL when you view a list) or an array of list paths. When an array is used, secondary navigation is rendered in the Admin UI.
						p The nav is also used to generate the links on the Admin UI home page; any lists that are registered but not included in the <code>nav</code> will be grouped at the bottom of the screen under the 'Other' heading.
				tr
					td <code>csv field delimiter</code> <code class="data-type">String</code>
					td Allow you to choose a custom field delimiter to be used for CSV export instead of the default comma.
				tr
					td <code>app</code> <code class="data-type">Object</code>
					td Instance of Express to be used instead of the default instance.
				tr
					td <code>mongoose</code> <code class="data-type">Object</code>
					td Instance of Mongoose to be used instead of the default instance.

			p.note The <code>app</code> and <code>mongoose</code> options replace the functionality of the <code>keystone.connect()</code> method which is now deprecated.  Due to changes in Express 4, `keystone.connect()` no longer works as expected.
				
			.code-header
				h4 Custom Navigation Example
				p If you had <code>User</code>, <code>Post</code> and <code>PostCategory</code> models, you could group the posts and post categories into a <strong>Content</strong> navigation item like this:
			pre: code.language-javascript
				| keystone.set('nav', {
				|     'users': 'users',
				|     'content': ['posts', 'post-categories']
				| });
		
			a(name='options-server')
			h3 Web Server Options
			
			p The following options control the configuration of your web server and the express app:
			
			table.table
				col(width=210)
				col
				tr
					td <code>env</code> <code class="data-type">String</code>
					td
						p The environment setting to use. The keys <strong>development</strong> and <strong>production</strong> are supported, and this will have an impact on things like caching compiled templates. Defaults to <code class="default-value">process.env.NODE_ENV || "development"</code>.
						p You should really <strong>set this to <code class="default-value">production</code> for your production servers</strong> using the <code>NODE_ENV</code> environment variable. Several other modules expect this convention also.
				tr
					td <code>port</code> <code class="data-type">Number</code>
					td
						p The port to listen for request on. Defaults to <code class="default-value">process.env.PORT || 3000</code>
				tr
					td <code>host</code> <code class="data-type">String</code>
					td
						p The ip address to listen for request on. Defaults to <code class="default-value">process.env.IP || '127.0.0.1'</code>
						p <code>port</code> must be set (either by option or env variable) or the <code>host</code> option will be ignored.
				tr
					td <code>views</code> <code class="data-type">String</code>
					td
						p The path to your application's <strong>view templates</strong>. This is required for using the <code>keystone.View</code> Class, and will also be set on the express app.
						p If you're following the <a href="/guide#start_structure">recommended project structure</a>, this should be set to <code class="default-value">"/templates/views"</code>.
				tr
					td <code>view engine</code> <code class="data-type">String</code>
					td
						p The template engine to use by default. Any engine with express support should work. <strong>Jade</strong> is included with Keystone, but you will have to add any alternate engine to your project's dependencies in your <code>package.json</code>.
						p This option is set on the express app (<a href="http://expressjs.com/api.html#app.engine" target="_blank">see docs here</a>).
				tr
					td <code>custom engine</code> <code class="data-type">Function</code>
					td
						p If you want to use a custom template engine, set this option to the function that should be used to process your templates.
						p See below for an example of how to use the <a href="http://paularmstrong.github.io/swig/" target="_blank">Swig</a> template engine.
				tr
					td <code>view cache</code> <code class="data-type">Boolean</code>
					td
						p This option is passed through to Express, and controls whether compiled view templates are cached between requests.
						p It defaults to <code class="default-value">true</code> in production, or <code class="default-value">false</code> otherwise so there is rarely any reason to set it explicitly.
				tr
					td <code>locals</code> <code class="data-type">Object</code>
					td
						p The default local variables to pass to your view templates.
						p Routes can extend or change local variables by modifying <code>res.locals</code>.
				tr
					td <code>static</code> <code class="data-type">String</code> or <code class="data-type">Array</code>
					td
						p One or more paths to your application's static files. Setting this will include the <code>serve-static</code> middleware.
						p If you're following the <a href="/guide#start_structure">recommended project structure</a>, this should be set to <code class="default-value">'public'</code>.
				tr
					td <code>static options</code> <code class="data-type">Object</code>
					td
						p Optional config options that will be passed to the <code>serve-static</code> middleware (<a href="https://github.com/expressjs/serve-static" target="_blank">see docs here</a>).
				tr
					td <code>less</code> <code class="data-type">String</code> or <code class="data-type">Array</code>
					td
						p If you want Keystone to automatically compile <strong>.less</strong> files into <strong>.css</strong> files, set this value to the same path as the <code>static</code> option.
						p When this option is set, any requests to a <strong>.css</strong> or <strong>.min.css</strong> file will first check for a <strong>.less</strong> file with the same name, and if one is found, the css file will be generated.
				tr
					td <code>less options</code> <code class="data-type">Object</code>
					td
						p Optional config options that will be passed to the <code>less</code> middleware; see <a href="https://github.com/emberfeather/less.js-middleware" target="_blank">github.com/emberfeather/less.js-middleware</a> for more information.
				tr
					td <code>sass</code> <code class="data-type">String</code> or <code class="data-type">Array</code>
					td
						p If you want Keystone to automatically compile <strong>.sass</strong> files into <strong>.css</strong> files, set this value to the same path as the <code>static</code> option.
						p When this option is set, any requests to a <strong>.css</strong> or <strong>.min.css</strong> file will first check for a <strong>.sass</strong> file with the same name, and if one is found, the css file will be generated.
						p.note Note that enabling this option requires you to have specified the <a href="https://github.com/sass/node-sass" target="_blank"><code>node-sass</code></a> package as a dependency in your project's <code>package.json</code> file; it is not automatically included with Keystone.
				tr
					td <code>sass options</code> <code class="data-type">Object</code>
					td
						p Optional config options that will be passed to the <code>sass</code> middleware; see <a href="https://github.com/sass/node-sass#options" target="_blank">github.com/sass/node-sass</a> for more information.
				tr
					td <code>favicon</code> <code class="data-type">String</code>
					td
						p The path to your application's <strong>favicon</strong>. Setting this will include the <code>serve-favicon</code> middleware. Should be relative to your project's root.
						p If you're following the <a href="/guide#start_structure">recommended project structure</a>, this should be set to <code class="default-value">"/public/favicon.ico"</code>.
{'fraction_non_alphanumeric': 0.10948967038561065, 'fraction_numerical': 0.002121070716497688, 'mean_word_length': 3.658893280632411, 'pattern_counts': {'":': 0, '<': 549, '<?xml version=': 0, '>': 549, 'https://': 9, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, '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': '5098532', 'n_tokens_mistral': 7850, 'n_tokens_neox': 6468, 'n_words': 2727}