-
Notifications
You must be signed in to change notification settings - Fork 723
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?"
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. |
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 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:
- 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
- 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.
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.
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
- 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
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
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
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.
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.
Yes! An ever growing one that you can add to as well. Check out Sites Using Prose
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 formatYYYY-MM-DD HH:MM
upon page creation. Useful when added to thedate:
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 ausers
list in your prose configuration, where each item is a map withlogin
anduser
key. Thelogin
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/
.