Permalink
Browse files

first commit

  • Loading branch information...
0 parents commit 165854b4933be7921ccd62883cb14e6ed5a43869 @niko committed Mar 3, 2011
Showing with 307 additions and 0 deletions.
  1. +6 −0 404.textile
  2. +6 −0 500.textile
  3. +3 −0 README.textile
  4. +12 −0 __global.textile
  5. +46 −0 app.textile
  6. +13 −0 caching.textile
  7. +13 −0 index.textile
  8. +54 −0 installation_and_usage.textile
  9. +33 −0 layouts.textile
  10. +27 −0 license.textile
  11. +21 −0 misc.textile
  12. +23 −0 overview.textile
  13. +50 −0 page_content.textile
@@ -0,0 +1,6 @@
+---
+:title: Not found
+
+++++body++++
+
+h1. No such file or directory
@@ -0,0 +1,6 @@
+---
+:title: Server Error
+
+++++body++++
+
+h1. Something went wrong
@@ -0,0 +1,3 @@
+h1. TinySite Documentation
+
+This are the _page content files_ for the TinySite documentation. Browse the documentation at "its Heroku home":http://tinysite.heroku.com.
@@ -0,0 +1,12 @@
+---
+:title: TinySite documentation
+:navigation:
+ :index: Home
+ :installation_and_usage: Installation and Usage
+ :overview: Overview
+ :layouts: The layouts
+ :page_content: The page content files
+ :app: The TinySite app
+ :caching: Caching
+ :misc: Misc
+ :license: License
@@ -0,0 +1,46 @@
+---
+:title: The TinySite app
+:description: The TinySite app is a simple and small (130LOC) ruby rack application.
+
+++++body++++
+
+h1. The TinySite app
+
+The app itself is really, really simple. All you need to get started is a @config.ru@ file:
+
+<pre><code>require 'tiny_site'
+
+use Rack::ContentLength
+
+run TinySite.new :file_path => 'http://dl.dropbox.com/u/[user_id]/my_site'
+</code></pre>
+
+The file path would be the folder in which the _page content files_ are available. Other supported parameters are @:image_path@ (defaults to @[file_path]/images@) and @cache_buster@ (a query string with which you can bust the internal cache and prevent HTTP caching for the given site). The @:image_path@ helps to keep urls of images in your textile short. Image tags which don't start with 'http://' or '/' will be prefixed by the @:image_path@.
+
+Of course you will want to serve some assets, too. Given this files and folders:
+
+<pre><code>config.ru
+layout.haml
+public/
+ javascript/
+ my.js
+ stylesheets/
+ my.css
+</code></pre>
+
+In this case the @config.ru@ will more look like this:
+
+<pre><code>require 'tiny_site'
+
+use Rack::CommonLogger
+use Rack::ContentLength
+use Rack::Static, :urls => ['/stylesheets','/javascript'], :root => 'public'
+
+run TinySite.new :cache_buster => 'preview',
+ :file_path => 'http://dl.dropbox.com/u/1343338/a_test',
+ :image_path => 'http://dl.dropbox.com/u/1343338/a_test/images',
+ :file_extension => :txt
+</code></pre>
+
+The file_extension is configurable if you need to use an editor that doesn't want to edit .textile files. Such as some smartphone dropbox clients which can only edit .txt files or the "TextDrop":http://textdropapp.com/ web client. I tried "Droptext for iPhone":http://itunes.apple.com/us/app/droptext-a-text-editor-for/id371880635?mt=8 and it works nicely! .textile can be added to the known extensions.
+
@@ -0,0 +1,13 @@
+---
+:title: Caching
+:description: How does the TinySite Caching work? Caching headers for Herokus Varnish.
+
+++++body++++
+
+h1. Caching
+
+TinySite adds HTTP caching headers to support Herokus Varnish cache. In addition to that fetched textile files are cached in-app for up to an hour. You can bust the cache by adding a configurable cache-busting query string. By default it's @bust@, so you would just add it to the URL like this: @http://foo/bar?bust@. In addition to clear the internal cache this adds a cache-control header to prevent caching in any HTTP cache between you and the app.
+
+You can use the cache buster to make changes to the page immediately visible for you to review them (and still others will _most likely_ get the old version for quite some time). I couldn't figure out a possibility to expire Herokus Varnish cache on demand, so at the moment you have no control over when exactly changes made are visible. It could take up to two hours (one for the internal content file cache and one for the external HTTP cache). As stated you can clear the internal cache of all pages by adding the cache buster query string and cut the time to max one hour.
+
+It would be a good idea to choose an own cache buster query string and keep it somewhat secret so other people can't fiddle with your apps cache.
@@ -0,0 +1,13 @@
+---
+:title: TinySite Documentation
+:description: The documentation for the TinySite static site engine https://github.com/niko/TinySite
+
+++++body++++
+
+h1. TinySite
+
+TinySite is a static small site engine with "Heroku":http://heroku.com and "Dropbox":http://www.dropbox.com/ in mind. The idea is to host the app for a site on Heroku and take advantage of their awesome application stack and provide the static content by Dropbox.
+
+For a guide to get you started immediately go directly to the "installation and usage page":installation_and_usage. This documentation app may serve you as a blueprint for your own app.
+
+If you like TinySite and don't have a Dropbox account already: Supporting this project by using my "Dropbox affiliate link":http://db.tt/zhjQbKF would be the easiest possibility to give back. And the best part is: When you use the affiliate link not only me, but you too get 250MB extra space on Dropbox.
@@ -0,0 +1,54 @@
+---
+:title: TinySite installation and usage
+:description: Installation and usage instructions TinySite
+
+++++body++++
+
+h1. Installation and Usage
+
+In your shell:
+
+<pre><code>gem install tiny_site</code></pre>
+
+In the config.ru of your Rack application
+
+<pre><code>require 'tiny_site'
+run TinySite.new :file_path => 'http://dl.dropbox.com/u/[user_id]/[path_to_files]'
+</code></pre>
+
+Run it:
+
+<pre><code>rackup config.ru</code></pre>
+
+h2. Use this very app as example
+
+To get started you can check out the TinySite documentation app:
+
+<pre><code>git clone git://github.com/niko/TinySite_documentation_app.git
+cd TinySite_documentation_app
+heroku create your-new-shiny-site --stack bamboo-mri-1.9.2
+git push heroku master
+heroku open
+</code></pre>
+
+h2. Change the content of the pages
+
+<pre><code>cd ~/Dropbox/Public/
+git clone git://github.com/niko/TinySite_documentation_files.git
+</code></pre>
+
+Change the name of the checked out folder to your liking.
+
+Then open the Dropbox website and copy the public link to the newly created folder. Enter the name of the folder as the @:file_path@ parameter in @config.ru@. Push to heroku:
+
+<pre><code>git push heroku master</code></pre>
+
+h2. After testing
+
+If you created a test app on heroku you should perhaps destroy it afterwards:
+
+<pre><code>heroku destroy --confirm your-new-shiny-site</code></pre>
+
+h2. Further steps
+
+* Adopt and add layout, styles, javascript
@@ -0,0 +1,33 @@
+---
+:title: The TinySite layouts
+:description:
+
+++++body++++
+
+h2. The TinySite layouts
+
+Each page is rendered into a "HAML":http://haml-lang.com layout file. The parts of the page and a set of variables are provided by the page itself and a _global content file_. The layout file should be located next to the rackup file @config.ru@ and defaults to @layout.haml@. The layout file is configurable via @page[:layout]@ and @global[:layout]@.
+
+A minimal @layout.haml@ could look like this:
+
+<pre><code>!!!
+%html{:lang => "de"}
+ %head
+ %meta{:charset => "utf-8"}
+ %title= page[:title] || global[:title]
+ %link{:href => "/stylesheets/styles.css"}
+ %body
+ %header
+ %h1 Some title
+ %nav
+ ~ global['navigation']
+ %aside
+ ~ page['sidebar']
+ %section
+ ~ page['body']
+ %footer
+</code></pre>[1]
+
+Note the use of @page[:title]@, @global[:title]@, @global['navigation']@, @page['sidebar']@ and @page['body']@. These variables are defined via...
+
+fn1. Also note the usage of @~@ as the HAML evaluation method. This prevents indentation. It's needed if you have code blocks (or other whitespace sensitive tags) in your Textile.
@@ -0,0 +1,27 @@
+---
+:title: Licence
+:description: TinySite is published under the MIT license
+
+++++body++++
+
+The MIT License
+
+Copyright (c) 2011 Niko Dittman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
@@ -0,0 +1,21 @@
+---
+:title: Miscellaneous - ToDo, credits, current state
+:description: The documentation for the TinySite static site engine https://github.com/niko/TinySite
+
+++++body++++
+
+h1. Miscellaneous
+
+h2. ToDo
+
+* More robust parsing error handling
+* Test helpers for layout-testing
+* Perhaps add a helper for the layout?
+
+h2. Credits
+
+* "Florian Hanke":https://github.com/floere for constant feedback
+
+h2. Current state of TinySite
+
+TinySite is currently alpha software. Patches and Bugreports are welcome.
@@ -0,0 +1,23 @@
+---
+:title: TinySite overview
+:description:
+
+++++body++++
+
+h1. TinySite overview
+
+TinySite itself is a tiny (hence the name) pure Rack application, sporting a mere 130 LOC.
+
+As already stated TinySite was designed with Heroku and Dropbox in mind. But of course TinySite will work at any other "Ruby":http://www.ruby-lang.org hoster as well and is easy to be self hosted (it's just "Rack":http://rack.rubyforge.org). And of course any other HTTP server or even local files will work for the content.
+
+With the Heroku/Dropbox combination TinySite provides:
+
+* Easy local editing of "YAML":http://en.wikipedia.org/wiki/YAML & "Textile":http://en.wikipedia.org/wiki/Textile_(markup_language) based _page content files_.
+* Versioning of _page content files_.
+* Give other people access to edit all pages or just some (via Dropbox folder sharing).
+* Easy drag and drop image (and other asset) upload.
+* Edit page form your iPhone or Android phone (via Dropbox edit app).
+* An own Heroku subdomain (and it's cheap to register an own domain for it).
+* Take full advantage of Herokus caching infrastructure.
+
+So how does it work?
@@ -0,0 +1,50 @@
+---
+:title: The TinySite page content format
+:description: Textile and YAML are the foundation of TinySites page content format.
+
+++++body++++
+
+h1. The TinySite page content format
+
+... are based on a YAML header a several Textile body parts. A simple one would look like this:
+
+<pre><code>---
+:title: My Page
+:description: It's uber-awesome!
+
+++++sidebar++++
+
+!some.png!
+
+Orem ipsum dolor sit amet, consectetur adipisicing elit, sed do
+eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+++++body++++
+
+h1. Hey, Dude!
+
+Lorem ipsum dolor sit amet, consectetur adipisicing elit,
+sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+</code></pre>[1]
+
+This gives the layout access to these variables: @page[:title]@, @page[:description]@, @page['sidebar']@ and @page['body']@.
+
+Analog to the @page@ variables the @global@ variables are set via the content of the @__global.textile@ file. A typical one would perhaps look like this:
+
+<pre><code>---
+:keywords: bla, blub, ...
+
+++++navigation++++
+
+* "Home":/
+* "One":one
+</code></pre>[1]
+
+With this in place the layout has access to these variables: @global[:keywords]@ and @global['navigation']@. The @__global@ file would be the place to add a footer, too.
+
+The filenames derive directly from the path. Subfolders are supported. With the above navigation in place you would need an @index.textile@ file and a @one.textile@ file next to your @__global.textile@ file.
+
+Besides the @page@ and the @global@ variable the layout hast access to a @env@ hash containing the current path and the current query string: @env[:path]@ and @env[:query_string]@.
+
+fn1. Note that I added a single whitespace to the end of the ++++variable++++ declaration lines to prevent TinySite from parsing the lines. If you copy the code you have to remove the whitespace.
+

0 comments on commit 165854b

Please sign in to comment.