prose / prose

A Content Editor for GitHub.

Prose

Prose provides a beautifully simple content authoring environment for CMS-free websites. It's a web-based interface for managing content on GitHub. Use it to create, edit, and delete files, and save your changes directly to GitHub. Host your website on GitHub Pages for free, or set up your own GitHub webhook server.

Read more about Prose

Setting up Prose with your site

Prose supports configuration settings with a variety of options, which makes it easy to adjust the application to support your project needs. Read the Getting Started Guide to learn more.

Installation and developing

Help contribute

Prose project is currently looking for new maintainers.

Prose is hosted at Prose.io, or you can use on your own server. For installation instructions and contributing guidelines, please read contributing.md. For deploying to your own server, read deployment.md.

Getting help

Have questions? Jump into the #prose channel on irc.freenode.net.

New to Internet Relay Chat? Join quickly & easily using your Web browser or sign-up for a no-cost account on IRCcloud.

prose's Issues

UI Stuff

• A dedicated icon for repositories would be great (as we have it for posts and folders)
• Shadows should be included in the sprite
• Small folder icon for the breadcrumbs (we have overview, repo, and file)
• More spacing in the sprite so we don't see multiple icons at once (e.g. in the path)

Cancel a save event and label wording

We should give a user the ability to cancel a save event when the user has selected, 'save' additionally, the published label should switch to read 'Revision message' or 'Commit message'

Support for browsing revision history

Support for browsing revision history / rolling back changes (unclear whether that's possible w/ current API)

Sticky footer

Make footer sticky. See Substance.io for that.

Consider .markdown & .md file extension.

utf-8 characters incorrectly displayed

Looks like the page has correct meta headers, might be an ajax bug.

Cross browser testing

We need to do cross browser testing. For an initial launch, we need to at least be able to say which browsers we support. For Mix launch we need to do real browser review.

The problem with listing Jekyll repositories

Github has an API to list the repositories of a certain user. Private repos are not included yet for whatever reason. I need to investigate more.

However.. the problem is that we need a lot of requests to determine whether a repository is a valid Jekyll site or not. Github is not willing to change the API for us (e.g. listing the branches right away)... sooo let me give me an example:

Repo A master (has no _config.yml) gh-pages (has a config.yml)
Repo B gh-pages (has no config.yml)
Repo C master (has a config.yml)

So in order to determine whether a repo can be managed by Columnist we need to implement a fuzzy check per returned repository. This could look like the following

1. is there a _config.yml within master? if yes -> consider this repo a Jekyll site and open the master branch
2. if not, is there a _config.yml within gh-pages? if yes -> consider this a Jekyll site and open the gh-pages branch
3. if not -> hide from the list

Given that a user has 50 repositories, we'd need 1+50*2 requests to actually just show the list of Sites that can be managed. I don't want to invest too much time here, because I'm not happy with the guessing approach. I'd rather go for listing all repos with a single request and signal a dead end (this is no valid Jekyll repository). Not exactly cool from a UX perspective, but that's the only solution that is reasonable for me right now. :(

Cut off long filenames

Big ass feedback ticket

Poole feedback

Just took Poole for a spin, it is looking really awesome. Here's a list of issues I ran into, broken down by immediate launch blockers, MixMarket launch blockers and random items.

This likely needs to be broken up into multiple tickets - @michael, @dhcole - let's talk tomorrow when @michael is back in.

/cc @Ericg

Immediate launch blockers

This is stuff that are outright serious bugs or that appears minor and easily addressable before a first launch + public comms effort.

• Minor: Get client ID out of repository (switch _config.yml to _config.yml.example?)
• Homescreen: I know there are limitations around what repos we can show, but I wonder whether we can do something more useful than this. E. g.: what about asking a user to enter a repo name in a text field and remember past repos entered in a cookie?
• Minor: We should make the not a valid jekyll site message less jarring. Let's just not use red and simplify to "Not a Jekyll site". Same here - note - already tinkered with messages.
• Minor: let's kill this horizontal scroll bar.
• When I change a blog post from private to public the bar turns green, pad lock icon turns to check mark, I save. Now:
  • Should we close gear drop down when hitting save? Somehow this is not rolling right.
  • When I leave post and come back, bar is not green, padlock icon is back (but post is public).
• I like the README.md file as an intro to poole place for now, we should add an 'Installation' section, walking step by step through setting up your own Poole - I know this is going to be short, this is exactly what is going to be exciting about it :).
• I changed the footer branding to something less heavy handed and removed the MixMarket reference. We should use a logo. @Ericg: we should talk whether we want to DevSeed or MapBox brand this. I'm leaning towards DevSeed as this is going to help us fish for consulting work.
• Possibly just minor: I think the 'new post' button location is… odd. It seems to be a compromise - do we have quick better ideas?
• Minor: Logo slips under repos button (Chrome).
• Clicking on the 'sheets' directory in michael/map-site I get this error.
• Minor: when opening a post, metadata drop down flickers open for a split second before closing.
• Safari 5.1.2: When clicking on a repo, repo does not open, remains a grey rectangle.
• When creating a new post, I can't click on the current repository's breadcrumb - forcing me to do a detour through the all repo listing.
• If I create a new post, save it, then try to rename it, I actually create a copy. Sometimes I could rename the original doc again and get a copy instead, sometimes I couldn't: the second renaming attempt succeeding. Here is a screenshot somewhat illustrating the result.
• Trying to run poole locally I can't authenticate through the proxy - what's the way to set Poole up for dev?

MixMarket launch blockers

This is stuff I see coming up for MixMarket.

• Copying metadata from old docs is tedious, looking forward on how we can support templates like a blog post template or an about page template.
• And related: Schema validation.
• What else are we seeing here?

Other

Any other stuff.

• Fill out form, navigate off page, hit back - all text entered is gone. Not sure what's a good way to solve this, but we're breaking an expectation here.
• Should we show front matter keys title in the preview? Subtitle? Not sure.
• We should get a domain or at least subdomain: http://pooleapp.com, http://poole.developmentseed.org
• Interaction is actually quite snappy, long directories like the devseed blog dir for 2011 is obviously a little slow, we should add a spinner.
• I do like the large doc viz on the one hand, but it breaks for (common) long filenames and long directory listings.
• Any sense of what it would take to support revisions and rolling back revisions?

Branding Poole

I think Poole should have its own domain and be its own project, tied back to Development Seed, just like Mapbox is. While MapBox is clearly a bigger project, I think it makes sense for Development Seed to be a place that releases products to help with a variety of things, and this is our product for web publishing.

I don't like branding it as MapBox, because I think there is not really any connection to the work MapBox does. While we may use Poole on things like the Map Sites, its specifically designed to help custom consulting work, which falls under DS.

cc @lxbarth @gundersen @michael

Icon for Overview is missing in new sprite

Should be at: 0px 250px;

Columnist messes up user-defined metadata

Metadata editor

Prop up metadata editor. Will help make schema definition needs more concrete.

Queue or attempt validation more than once

If the server response is slow. I get this message a lot:

It's also an alert that pop's up twice.

Blogging Poole

@michael's plan is to finish open issues on Poole by Tue COB.

@gundersen:

Are we good to blog poole before we deliver to Mix right?

If so I'm seeing a blog post by @michael taking a tech/microsite angle on Development Seed going out on Tuesday or Wednesday next week.

We can then follow a mix centric blog post the week after.

/cc @michael, @dhcole

Implement UI concerning the publishing workflow

#3 States to be reflected:

Unpublished:

Status-Label: "Not yet published"
Actions: Publish

Published (no changes):

Status-Label: "Published"
Actions: Unpublish

Published (pending changes = once the user has made some changes to the document)

Status-Label: "Published"
Actions: Update (magically shows up when the user starts editing), Unpublish

Commit message

Once you hit the Publish or Update action, a message panel shows up that lets you enter a commit message, describing your changes.

Domain

• try to get poole user for poole.github.com
• otherwise get pooleapp.com

Exclude header on start page if unauthorized:

The header is redundant here, we should not show it on the start page. Michael, I poked around a little but was unable to figure out how to do this. It looks like this is a js thing that is a bit over my head.

Add schema validation to the Metadata Editor

JSON schema validation @yhahn suggested YAML format "in _config.yml or so for post validation, defining doc types and creation"

Nice to have: Fine Markdown Syntax Highlighting

Maybe we can adapt some styles from the TileMill Carto Editor?

License

@michael - also here in the editor - can you add a BSD license file?

Add loading indicator for load site + load post

Scan for layouts?

We could look at _layouts to determine the available layouts or require a list of usable layouts in _config.yml or maybe both. In many cases the layouts that should be offerred will be a subset of all that are available.

Smoothen the UI

Now that we're almost feature complete for the first solid version of Poole, we should do a quick design-refresh to put everything into place and make it a decent user experience. I talked to Saman, and he'll have a look at it, it's a second priority for him, so I don't want to block him on other stuff. @lxbarth does that sound good to you?

Style 'published' toggle

Should look like this when unpublished:

This when published:

I'm not sure how to do this off-hand, will get to it later if I have time.

Implement Markdown Preview

@tristen How would you do that in terms of the UI?

I'd prefer toggling between edit and preview mode and have the contents at the same place (that sheet of paper you know)

Use YAML syntax highlighting for frontmatter

Delete posts

Allow the deletion of posts. For now users can just hide them.

Publish toggle

I know this is an endless discussion. But now that we have such pretty published vs. private/locked icons. Why not using that icon for toggling between published and unpublished instead of the dropdown.

When mouseover the icon we could display "Publish" to the left of the icon, and finally we have a one click unlock/publish action. Thoughts?

Exclude non-Jekyll repositories from the site selection

Seriously consider webwriter integration for bad-ass markdown editing

http://icebeat.github.com/webwriter/

Use the Repository Selector (sitting) in the Menu for navigating back to the posts page

Clicking on the label should take you to the Posts page, while clicking on the down arrow lets you switch between repositories.

When updating a post, ask for a remark (aka commit message)

Monday hacking

That's what I want to implement on Monday:

• Implement New Post properly
• Delete posts
• Find a way to avoid dead ends (e.g. dynamically fetching and exposing relevant branches)
• Talk about UI workflow

Consider implementing a Pull-Request Workflow in order to be able to review changes

This implies we ideally allow cross-user editing (based on authorization).

Example:

Reviewer bonniebogle should be able to access mapbox/mapbox.github.com to review changes that tristen has made on that same repository.

Consider and properly handle tags with Metadata Editor

Better handle post format (html/textile/md/xml/txt)

Currently assumes Markdown, would be nice to intelligently handle the various formats supported by Jekyll.

Error handling

Still open:

• Dealing with wrongly formatted metadata
• Dealing with invalid filenames

We need proper (unobstrusive) notifications for this.

implement a better loading screen

Replace the 'one second' message with a spinner gif.

Based on the amount of content the Markdown editor should expand accordingly

Use indicator during saving

"Save" -> turns into "saving ..." (some loading animation 45deg stripes?) -> turns into "Saved" (maybe with a checkmark)?

Decide on an approach to markdown syntax assistance

I see 2 options:

1. A link in the menu nav for a cheat sheet modal popup, like github
2. A toolbar that adds markdown to your content

Also, in combination with these, we should consider doing the following:

• Adding syntax highlighting to mardown
• including keybindings for bold/emphasis/titles

Michael, what do you see as the best approach here? I think #1 is better than #2, and if we can implement syntax highlighting and keybindings we should go for it.

4 space indents

Please switch to 4 space indentation. Office wide convention.

Remove create post form and populate defaults in form

What do you think about side stepping the whole new post page form and populate 'Untitled Post' with todays date from the form itself. I'm not sure this prerequisite step is necessary and provides a consistant interface as to where the title,subtitle and revision date is located in the app.

Check explicitly for hidden === true to consider postings hidden

Updated loading spinner.

Just changed the background to something lighter while we're loading a repository. The spinner needs to be adjusted now.

Queue or attempt validation more than once/

If the server response is slow. I get this message a lot:

It's also an alert that pop's up twice.

Add schema validation to the Metadata Editor

JSON schema validation @yhahn suggested YAML format "in _config.yml or so for post validation, defining doc types and creation"

Implement user authentication

Store credentials in cookie session. Should we consider this secure? I guess not.

Maybe we can use other authentication mechanisms (OAuth, API token). However I'm afraid we have to figure that out later.