forked from prose/prose
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
9 additions
and
121 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,131 +1,19 @@ | ||
| Prose | ||
| ================= | ||
| # Prose | ||
|
|
||
| **Prose** is a web-interface dedicated for managing dynamic content of Jekyll-based websites. Users of Jekyll can create, edit and delete files that live within the `_posts` directory. Prose can be considered a smart way of publishing for hackers and [humans](http://www.fyears.org/2012/05/jekyll-for-hackers-not-for-humans), solving the issue that Jekyll is has not yet been suitable for less-technical content editors. | ||
| [Prose](http://prose.io) is a web-based interface for managing text-based content in your GitHub repositories. Use it to create, edit, and delete files, and save your changes directly to GitHub. | ||
|
|
||
| While developers can still enjoy all freedom the Jekyll framework provides, editors can easily access, edit and publish content using a visual interface. Here is how it works: | ||
| Prose is great for making quick updates to your code or managing your blog. Prose pays special attention to [Jekyll sites](https://github.com/mojombo/jekyll) [hosted on GitHub Pages](http://pages.github.com) with Markdown text preview and syntax reference. It's [configurable](help/handbook.html#set_root_url) to restrict users to files that live within the `_posts` directory so you can use it to manage the content on your blog without fear of changing other critical files. Using Jekyll in conjunction with Prose is a smart way of maintaining websites for developers and editors alike by allowing them to use a visual, web-based tool to manage the content. | ||
|
|
||
| Login with your Github User | ||
| ----------------- | ||
| [Get started now](/help/getting-started.html) or learn more about [using Jekyll to design flexible static websites](http://developmentseed.org/blog/2011/09/09/jekyll-github-pages/). | ||
|
|
||
| It was challenging, but Prose supports OAuth. I think it's very important to use OAuth over Basic Authentication, since Github data can be very sensible and no one wants to risk getting his password sniffed. | ||
|  | ||
|
|
||
|  | ||
|
|
||
| ## Future plans | ||
|
|
||
| Browse Repositories | ||
| ----------------- | ||
| This is a first release dedicated to developers at this early stage. It will be buggy as we work out the kinks, but we plan to make this rock solid and extend the feature set (while keeping the UI as minimal as possible). We hope Prose + Jekyll will provide a simple, efficient alternative to traditional CMSs that require web and database servers to host content. | ||
|
|
||
| This is the landing page, it gives you all the repositories you have access to. If a Jekyll site has multiple branches, you are prompted to select your desired branch, otherwise, you jump into the repo directly. | ||
|
|
||
|  | ||
| ## Get involved | ||
|
|
||
|
|
||
| Browsing Posts | ||
| ----------------- | ||
|
|
||
| Once you have selected a repository, you can browse your posts and sub-folders in a traditional file-browser-ish manner. You can create new files here as well, which immediately opens an empty document for you, which you can save after populating it with some text. | ||
|
|
||
|  | ||
|
|
||
|
|
||
| Edit Posts | ||
| ----------------- | ||
|
|
||
| We use CodeMirror, a great software that makes browser-based editing a pleasure (the first time). Compared to a regular textarea, which has an annoying inline scoller this is a huge step forward I think. | ||
|
|
||
|  | ||
|
|
||
|
|
||
| Preview | ||
| ----------------- | ||
|
|
||
| You can instantly preview your writing by either clicking the preview icon at the document menu bar, or use that fance keyboard combo ctrl+shift+p to toggle Preview on and off. | ||
|
|
||
|  | ||
|
|
||
|
|
||
| Publish | ||
| ----------------- | ||
|
|
||
| Once you are ready, you can easily publish your article, which lets it show up on the actual webpage/blog. | ||
|
|
||
|  | ||
|
|
||
|
|
||
| Metadata | ||
| ----------------- | ||
|
|
||
| Take full control about your post, and edit Metadata aka the YAML frontmatter. No limitations. | ||
|
|
||
|  | ||
|
|
||
|
|
||
| Architecture | ||
| ================= | ||
|
|
||
| Prose itself is just a static webpage, and doesn't require any server-side bits. Instead it interacts directly with the Github API for managing your repo's contents. | ||
|
|
||
| The Github API is somewhat funky from time to time, and hard to debug. We had to be aware of CORS issues and properly setting up headers for authorization. What's challenging here, is that Github just offers a low level API (around trees and blobs), which is problematic in many cases, as it requires a lot of subsequent requests to do simple things, which slows down site performance. That's why creating a good architecture was crucial to manage the complexity. I ended up in abstracting the data layer into a separate module, Github.js. | ||
|
|
||
|
|
||
| Github.js | ||
| ----------------- | ||
|
|
||
| [Github.js](https://github.com/michael/github) is a higher-level wrapper around the Github API. It's intended for exactly our use case, namely interacting with Github from the browser. It supports reading, writing, renaming and deleting files. Goal was to have a simple data abstraction layer, nothing to fancy, but providing exactly the operations we need. | ||
|
|
||
|
|
||
| Gatekeeper | ||
| ----------------- | ||
|
|
||
| Because of some [security-related limitations](http://blog.vjeux.com/2012/javascript/github-oauth-login-browser-side.html), Github prevents you from implementing the OAuth Web Application Flow on a client-side only application. | ||
|
|
||
| This is a real bummer. So we built [Gatekeeper](http://github.com/developmentseed/gatekeeper), which is the missing piece you need in order to make OAuth work. | ||
|
|
||
|
|
||
| Installation | ||
| ================= | ||
|
|
||
| 1. Fork and clone the repo in order to run your own instance of Prose. | ||
|
|
||
| 2. Setup a Github application, so CORS requests are possible as well as OAuth authentication. | ||
|
|
||
|  | ||
|
|
||
| 3. Setup Gatekeeper. | ||
|
|
||
| Follow the instructions here and fill in the information that is provided after registering a new Github Application. | ||
|
|
||
| 4. Adjust `_config.yml`. | ||
|
|
||
| ``` | ||
| auto: true | ||
| server: true | ||
| oauth_client_id: your_oauth_client_id | ||
| gatekeeper_url: http://gatekeeper.example.com | ||
| exclude: | ||
| - .gitignore | ||
| - README.md | ||
| ``` | ||
|
|
||
| 5. Run it. | ||
| ``` | ||
| server:prose prose$ jekyll | ||
| ``` | ||
|
|
||
| Limitations | ||
| ================= | ||
|
|
||
| The Github API comes with a number of limitations because of its low-level nature. Here is a the list of known issues related to that. I hope the folks at Github can help us (with some minor additions to their API) so we can eliminate them. | ||
|
|
||
| - Listing Repositories | ||
|
|
||
| When listing the repositories, we can't determine which of them are actual Jekyll sites. Theoretically we could, by issuing a separate request that fetches repository information (such as branches) and looks for a `_config.yml` file. However this is way to slow, so we have to do it on-demand as you click on a repository. | ||
|
|
||
| - Organizations | ||
|
|
||
| Repositories that live within your organizations can only be accessed by entering the url (`/:organization/:repo/:branch`) manually. | ||
|
|
||
| - Deleting and renaming files | ||
|
|
||
| This requires a full tree to be written involving a new commit that points to that tree. In fact this is not a big problem with small repositories, but once they get bigger it's not only a performance issue, you'll get errors. Be aware that you may not (yet) be able to rename or delete files when working with bigger repositories. | ||
| You already discovered the source code. And now that you're here, why not start contributing? :) |