Prose Configuration

Configurations are managed as a text based document. To start, create a _prose.yml file in the root of your project contents. Note: If your project uses Jekyll add any configurations as an entry in _config.yml.

Like YAML docs, options are nested after defining prose: as the heading:

prose:
    # Configurations ...

See a complete example on the Getting-Started page under "Configurations," or see the link to example configurations below under "Is there a list of example configurations anywhere?"

Options

Setting	Jekyll Specific?	Description
rooturl: "DIRECTORY NAME"	No	Restricts authoring access to a directory
ignore: ['file_a.html', '_config.yml']	No	Array of files to ignore and hide in Prose
siteurl: "http://domain-name.com"	Yes	Turns on Jekyll live previews. The url is the homepage of the live site.
site:	Yes	This field accepts a list of absolute .JSONP paths to content that is loaded during Jekyll live previews. This is particularly useful for building out tags or categories that should be present during preview.
media: "DIRECTORY NAME"	No	Specify a media directory uploading images defaults to. When media is added to this directory, a listing of available assets is populated from the image dropdown link on markdown files
relativeLinks: "ABSOLUTE-URL.JSONP"	No	Displays a list of links to a user from the link dropdown on markdown files. The url should be JSONP and structured as an array of objects in the following format: {"text": "Local Link", "href": "http://mapbox.com" }
metadata: See options below	Yes	Removes editing yml front matter to provide clean dropdown forms to select default options

Metadata Configuration

Metadata configuration refers to the yaml frontmatter present in Jekyll sites. Prose allows you to turn these key value pairings into friendly form elements or hide them completely if fields should only accept a default value. Overall, this provides a simpler interface where you are editing the values and not the keys themselves. If a front matter field is not defined in the configuration the output of this is defaulted to a raw output.

The metadata entry begins with the name metadata: followed by the directory path to files prose should apply these rules to.

metadata:
  _posts:
    - # Elements ..

For each front matter field you define in your configuration file there should be a name value that matched the name of the frontmatter key and a field object that describes what html element is used and how this should be displayed to the user.

As an example, an entry like layout: blog in your file should be configured in the following way:

- name: "layout"
  field:
    element: "hidden"
    value: "blog"

Where name is an exact match to the frontmatter key. Here I have chosen to display this element as hidden to the user as this should never be altered. Depending on the field element you use there are a number of options you can provide. Check out the following list of options available below:

Form field attributes

Text

• element: text
• label: (optional string) Label to the user
• help: (optional string) Help/description to accompany a label
• value: (optional string) A default value
• placeholder: (optional string) Helper text in the input if no value is provided.
• type: text

Textarea

• element: textarea
• label: (optional string) Label to the user
• help: (optional string) Help/description to accompany a label
• value: (optional string) A default value
• placeholder: (optional string) Helper text in the textarea if no value is provided.

Select & Multiselect

Allow a user to make one or more selections

• element: select OR multiselect
• label: (optional string) Label to the user
• help: (optional string) Help/description to accompany a label
• value: (optional string) A default value (multiselect elements can accept either a single value, or a list of default values)
• options: (array or string) If the value is a string, prose expects this to be an https url that links to a JSONP file structured in the following format: callback([{"name": "Granny Apples", "value": "granny-apples" }]). If your metadata configuration depends on multiple jsonp files, you must use different callback names by specifying ?callback={callback_name} to the end of the url. If this is an array the format should look like:

options:
  - name: 'Granny Apples'
    value: 'granny-apples'

• placeholder: (optional string) Helper text if no value is provided
• lang: (optional string) if a lang key is set this allows the option of filtering a JSONP response by language. Useful for multilingual sites in Jekyll

(Multiselect only)

• alterable: (optional boolean) true or false whether a user can add additional values. Useful for tags.

Hidden

This is particularly useful for frontmatter fields that should always have a fixed value and not changed. An good example is the layout field a file inherits.

• element: hidden
• value: (optional string) The default value

Number

• element: number
• label: (optional string) Label to the user
• help: (optional string) Help/description to accompany a label
• value: (optional integer) A default integer
• type: number

Button

A button can be used to toggle on and off the value

• element: button
• label: (optional string) Label to the user
• help: (optional string) Help/description to accompany a label
• on: (string) The name of the on value
• off: (string) The name of the off value

Checkbox

Toggles on a true or false state

• element: checkbox
• label: (optional string) Label to the user
• help: (optional string) Help/description to accompany a label
• value: (boolean) true or false

Post titles

You can provide a more user-friendly interface for setting the titles of posts by specifying a title field:

metadata:
  _posts:
    - name: "title"
      field:
        element: "text"
        label: "title"

This replaces the filename field in the UI (which, by default, displays the whole filename, like 2014-03-02-goto-considered-harmful.md) with a field for a human-readable title (like "GOTO Considered Harmful"). Prose will then deduce the filename from the title, and save the title into the YAML front matter.

Working with content types in prose

Not all content is the same. Jekyll sites can have blogs, static pages, you name it! By structuring the type of content on your site into sub-directories you can create custom default metadata for each.

prose:
  metadata:
    _posts:
      - name: "category"
        field:
          element: "hidden"
          value: "articles"
    _posts/blog:
      - name: "category"
        field:
          element: "hidden"
          value: "blog"

To use the blog content type as defined above, you would navigate to the blog sub-directory of _posts (creating it if it does not already exist), then click New file. This will create a new piece of content with the blog content type fields loaded in the metadata editor.

Is there a list of example configurations anywhere?

Yes! An ever growing one that you can add to as well. Check out Sites Using Prose

Variables

These variables are placeholders that Prose will replace with real values when creating a new page. Configure these as the value in your metadata presets (and not the placeholder).

• CURRENT_DATETIME: Inserts the current date and time in the following format YYYY-MM-DD HH:MM upon page creation. Useful when added to the date: field in the frontmatter.
• CURRENT_USER: Inserts the current username upon page creation. By default, the username is what Prose uses to authenticate. You can change this behavior by including a users list in your prose configuration, where each item is a map with login and user key. The login should match your authenticated login name.

So if your Github handle is dereklieu, then your prose configuration would look like this:

prose:
  metadata:
    _posts:
      - name: "User"
        field:
          element: "hidden"
          value: CURRENT_USER
  users:
    - login: "dereklieu"
      user: "Derek Lieu"

You can also use the CURRENT_USER placeholder to set default rooturls for repos with many users, ie. rooturl: _posts/CURRENT_USER/.