This handbook is a work in progress. We’re going to cover certain aspects related to using Prose.io. It’s intended to be extended on-demand as questions come up. We’d like to invite you to contribute to the documentation. Just modify this file, and send us pull requests.

Getting started

See the Getting started guide.

Configuration of your site

Configuration is optional, but in many cases you might want to have more control about the behavior of Prose. You can configure it by including a prose property in your _config.yml.

Set Root URL

In order to restrict access to a certain directory you can specify a rooturl property.

auto: true
server: true
permalink: none
baseurl: "site_name"
prose:
  rooturl: "_posts"

Metadata defaults

Metadata defaults can be used to prepopulate metadata of posts based on the directory they’re going to live in. So for the blog on your site you might want to specify title and abstract properties while for project entries people should fill in attributes such as a project name and image (thumbnail). Be aware that metadata defaults need to be specified using the YAML block syntax.

auto: true
server: true
prose:
  metadata:
    "_posts/blog": |
      title:    "Title of your article"
      abstract: "Abstract"
    "_posts/projects": |
      name: "Project Name"
      img:  "Project Thumbnail"

Make your website editable

You have probably seen the “Edit in Prose”-link that sits below our help articles, like this one (scroll down). You should consider doing that with your website too in order allow readers to contribute.

Essentially, this is as easy as including a link to the Prose edit page of the corresponding markdown file. You can copy it over from GitHub and add prose.io/# instead of github.com/ as a prefix.

For the Prose help pages we just added a prose_link property to the YAML frontmatter of our source files.

---
prose_link: http://prose.io/#prose/prose/edit/gh-pages/_posts/help/2012-06-20-internals.md
---

And in the help pages template used this markup:

html <div class="improve-article-wrapper"> <div class="improve-article"> <a class="button" href="http://prose.io/#prose/prose/edit/gh-pages/_posts/help/2012-06-20-handbook.md">Edit in Prose</a> <p> This article has been written and published using <a href="http://prose.io" target="_blank">Prose</a>. Please help improving this documentation by contributing to the text. </p> </div> </div>

Known Issues

This is brand-new software, and there are some known issues you should be aware of.

I have deleted a file, but it’s still there.

Wait a little bit. Then refresh. It may take some time until the Github API is reflecting the changes.