updated branch; this is ready for review for inclusion in IkIWiki

[git.ikiwiki.info.git] / doc / plugins / amazon_s3.mdwn

diff --git a/doc/plugins/amazon_s3.mdwn b/doc/plugins/amazon_s3.mdwn
index caa0c01530be6251683de0fe8b7bda6b790e0354..52c05f9ae489e8a7a60c0ae1b882848825ee7060 100644 (file)
--- a/doc/plugins/amazon_s3.mdwn
+++ b/doc/plugins/amazon_s3.mdwn
@@ -1,12 +1,12 @@
-[[template id=plugin name=amazon_s3 author="[[Joey]]"]]
-[[tag type/special-purpose]]
+[[!template id=plugin name=amazon_s3 author="[[Joey]]"]]
+[[!tag type/special-purpose]]

 
 This plugin allows ikiwiki to publish a wiki in the [Amazon Simple Storage
 Service](http://aws.amazon.com/s3) (S3). As pages are rendered, ikiwiki
 will upload them to Amazon S3. The entire wiki contents, aside from the
 ikiwiki CGI, can then be served directly out of Amazon S3.
 
 
 This plugin allows ikiwiki to publish a wiki in the [Amazon Simple Storage
 Service](http://aws.amazon.com/s3) (S3). As pages are rendered, ikiwiki
 will upload them to Amazon S3. The entire wiki contents, aside from the
 ikiwiki CGI, can then be served directly out of Amazon S3.
 

-You'll need the [[cpan Net::Amazon::S3]] and [[cpan File::MimeInfo]] perl
+You'll need the [[!cpan Net::Amazon::S3]] and [[!cpan File::MimeInfo]] perl

 modules and an Amazon S3 account to use this plugin.
 
 ## configuration
 modules and an Amazon S3 account to use this plugin.
 
 ## configuration


@@ -22,9 +22,10 @@ This plugin uses the following settings in the setup file:
   set it to "foo", then the url will be
   "http://foo.s3.amazonaws.com/wiki/".
 * `amazon_s3_prefix` - A prefix to prepend to each page name.
   set it to "foo", then the url will be
   "http://foo.s3.amazonaws.com/wiki/".
 * `amazon_s3_prefix` - A prefix to prepend to each page name.

-  The default is "wiki/". Note that due to S3 limitations (lack of support
-  for uploading a root key), it is not possible to set the prefix to an
-  empty string.
+  The default is "wiki/". Note: In order to host your site at the root,
+  it needs to be set to "", and you'll have to 
+  [read this](http://aws.typepad.com/aws/2011/02/host-your-static-website-on-amazon-s3.html)
+  for details about configuring your S3 bucket as a website.

 * `amazon_s3_location` - Optionally, this can be set to control which
   datacenter to use. For example, set it to "EU" to for Europe.
 * `amazon_s3_dupindex` - Normally, when `usedirs` is enabled,
 * `amazon_s3_location` - Optionally, this can be set to control which
   datacenter to use. For example, set it to "EU" to for Europe.
 * `amazon_s3_dupindex` - Normally, when `usedirs` is enabled,


@@ -33,7 +34,8 @@ This plugin uses the following settings in the setup file:
   "index.html" in their names to work, you can enable this option. Then
   each index.html file will be stored in S3 *twice*, under both names. This
   will use more disk and bandwidth, and is not recommended unless you really
   "index.html" in their names to work, you can enable this option. Then
   each index.html file will be stored in S3 *twice*, under both names. This
   will use more disk and bandwidth, and is not recommended unless you really

-  need it for some reason.
+  need it for some reason. These days, it's probably better to configure
+  your S3 bucket as a website.

 
 Note that you should still set `destdir` in the setup file. The files that
 are uploaded to Amazon S3 will still be written to the destdir, too.
 
 Note that you should still set `destdir` in the setup file. The files that
 are uploaded to Amazon S3 will still be written to the destdir, too.


@@ -46,11 +48,11 @@ The `hardlink` config file setting is not compatible with this plugin.
 
 ## data transfer notes
 
 
 ## data transfer notes
 

-If you run 'ikiwiki -setup my.setup' to force a rebuild of your wiki, the
+If you run 'ikiwiki --setup my.setup' to force a rebuild of your wiki, the

 entire thing will be re-uploaded to Amazon S3. This will take time, and
 cost you money, so it should be avoided as much as possible.
 
 entire thing will be re-uploaded to Amazon S3. This will take time, and
 cost you money, so it should be avoided as much as possible.
 

-If you run 'ikiwiki -setup my.setup -refresh', ikiwiki will only upload the
+If you run 'ikiwiki --setup my.setup --refresh', ikiwiki will only upload the

 modified pages that it refreshes. Faster and cheaper. Still, if you have
 very large pages (for example, a page that inlines hundreds of other pages
 .. or is just very large), the complete page contents will be re-uploaded
 modified pages that it refreshes. Faster and cheaper. Still, if you have
 very large pages (for example, a page that inlines hundreds of other pages
 .. or is just very large), the complete page contents will be re-uploaded


@@ -62,5 +64,5 @@ it will be re-uploaded, rather than copied.
 
 ## deleting a bucket
 
 
 ## deleting a bucket
 

-You can use "ikiwiki -setup my.setup --delete-bucket" to delete anything
+You can use "ikiwiki --setup my.setup --delete-bucket" to delete anything

 that's in the configured bucket, and remove the bucket.
 that's in the configured bucket, and remove the bucket.