deac/middleman-deploy
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Merge pull request #32 from rmm5t/readme-improvements

Browse source 
Reorganized the readme for better readability
This commit is contained in:
Tom Vaughan 2013-07-21 19:05:11 -07:00
commit 0ac2b4ad82
1 changed files with 88 additions and 119 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

177
README.md
View file

@ -1,155 +1,124 @@
Middleman Deploy - Deploy a [middleman](http://middlemanapp.com/) # middleman-deploy [![Build Status](https://travis-ci.org/tvaughan/middleman-deploy.png?branch=master)](https://travis-ci.org/tvaughan/middleman-deploy)
built site over rsync, ftp, sftp, or git (e.g. gh-pages on github).
[![Build Status](https://secure.travis-ci.org/tvaughan/middleman-deploy.png)](http://travis-ci.org/tvaughan/middleman-deploy) Deploys a [middleman](http://middlemanapp.com/) built site via **rsync**,
**ftp**, **sftp**, or **git** (e.g. gh-pages on github).
# QUICK START ## Installation
## Step 1 Add this to the Gemfile of the repository of your middleman site:
middleman init example-site ```ruby
cd example-site gem "middleman-deploy"
```
## Step 2 and run `bundle install`.
Edit `Gemfile`, and add: ## Usage
gem "middleman-deploy", ">= 0.1.0" ```
$ middleman build [--clean]
$ middleman deploy [--build-before]
```
Then run: To automatically run `middleman build` during `middleman deploy`, turn on the
`build_before` option while activating the deploy extension:
bundle install ```ruby
activate :deploy do |deploy|
# ...
deploy.build_before = true # default: false
end
```
## Step 3a - Rsync setup ## Possible Configurations
First be sure that `rsync` is installed. Middleman-deploy can deploy a site via rsync, ftp, sftp, or git.
**These settings are required.** ### rsync
Edit `config.rb`, and add: Make sure that `rsync` is installed, and activate the extension by adding the
following to `config.rb`:
activate :deploy do |deploy| ```ruby
activate :deploy do |deploy|
deploy.method = :rsync deploy.method = :rsync
deploy.user = "tvaughan" deploy.user = "tvaughan"
deploy.host = "www.example.com" deploy.host = "www.example.com"
deploy.path = "/srv/www/site" deploy.path = "/srv/www/site"
end # Optional Settings
# deploy.port = 5309 # ssh port, default: 22
# deploy.clean = true # remove orphaned files on remote host, default: false
end
```
Adjust these values accordingly. ### Git (e.g. GitHub Pages)
**These settings are optional.** Make sure that `git` is installed, and activate the extension by adding the
following to `config.rb`:
To use a particular SSH port, add: ```ruby
activate :deploy do |deploy|
deploy.port = 5309
Default is `22`.
To remove orphaned files or directories on the remote host, add:
deploy.clean = true
Default is `false`.
## Step 3b - Git setup
First be sure that `git` is installed.
**These settings are required.**
Edit `config.rb`, and add:
activate :deploy do |deploy|
deploy.method = :git deploy.method = :git
end # Optional Settings
# deploy.remote = "custom-remote" # remote name or git url, default: origin
# deploy.branch = "custom-branch" # default: gh-pages
end
```
By default this will deploy to the `gh-pages` branch on the `origin` If you use a remote name, you must first add it using `git remote add`. Run
remote. The `build` directory will become a git repo. `git remote -v` to see a list of possible remote names. If you use a git url,
it must end with '.git'.
**These settings are optional.** Afterwards, the `build` directory will become a git repo. This branch will be
created on the remote if it doesn't already exist.
To use a particular remote, add: ### FTP
deploy.remote = "some-other-remote-name" Activate the extension by adding the following to `config.rb`:
Default is `origin`. This can be a remote name or a git url. ```ruby
activate :deploy do |deploy|
If you use a remote name, you must first add it using `git remote
add`. Run `git remote -v` to see a list of possible remote names. If
you use a git url, it must end with '.git'.
To use a particular branch, add:
deploy.branch = "some-other-branch-name"
Default is `gh-pages`. This branch will be created on the remote if it
doesn't already exist.
## Step 3c - FTP setup
**These settings are required.**
Edit `config.rb`, and add:
activate :deploy do |deploy|
deploy.method = :ftp deploy.method = :ftp
deploy.host = "ftp.example.com" deploy.host = "ftp.example.com"
deploy.user = "tvaughan" deploy.user = "tvaughan"
deploy.password = "secret" deploy.password = "secret"
deploy.path = "/srv/www/site" deploy.path = "/srv/www/site"
end end
```
Adjust these values accordingly. ### SFTP
## Step 3d - SFTP setup Activate the extension by adding the following to `config.rb`:
**These settings are required.** ```ruby
activate :deploy do |deploy|
Edit `config.rb`, and add:
activate :deploy do |deploy|
deploy.method = :sftp deploy.method = :sftp
deploy.host = "sftp.example.com" deploy.host = "sftp.example.com"
deploy.user = "tvaughan" deploy.user = "tvaughan"
deploy.password = "secret" deploy.password = "secret"
deploy.path = "/srv/www/site" deploy.path = "/srv/www/site"
end end
```
Adjust these values accordingly. ## Breaking Changes
## Step 4 * `v0.1.0`
- Removed the `--clean` command-line option. This option only applied to
the rsync deploy method. The idea going forward is that command-line
options must apply to all deploy methods. Options that are specific to a
deploy method will only be available in `config.rb`.
- Removed `deploy` from the `after_build` hook. This caused a `deploy` to
be run each time `build` was called. This workflow never made
sense. `deploy` was added to the `after_build` hook simply because it
was available.
middleman build [--clean] ## Thanks!
middleman deploy [--build-before]
To run `middleman build` before `middleman deploy`, add:
deploy.build_before = true
Default is `false`.
## BREAKING CHANGES
* v0.1.0
* Removed the `--clean` command-line option. This option only applied
to the rsync deploy method. The idea going forward is that
command-line options must apply to all deploy methods. Options that
are specific to a deploy method will only be available in
`config.rb`.
* Removed `deploy` from the `after_build` hook. This caused a
`deploy` to be run each time `build` was called. This workflow never
made sense. `deploy` was added to the `after_build` hook simply
because it was available.
## THANKS
A **BIG** thanks to A **BIG** thanks to
[everyone who has contributed](https://github.com/tvaughan/middleman-deploy/graphs/contributors)! [everyone who has contributed](https://github.com/tvaughan/middleman-deploy/graphs/contributors)!
Almost all pull requests are accepted. Almost all pull requests are accepted.
## NOTES ## Other
Inspired by the rsync task in Inspired by the rsync task in
[Octopress](https://github.com/imathis/octopress). [Octopress](https://github.com/imathis/octopress).