Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Site generation and release process #709

Merged
merged 5 commits into from Dec 31, 2012

Conversation

Projects
None yet
9 participants
Contributor

mojombo commented Dec 26, 2012

I'd like to deploy @cobyism's awesome site to jekyllrb.com soon. Before we do that it's prudent to have a process in place whereby the site can be modified, previewed, and deployed with ease. This branch brings the site files into the master branch (under the site dir) and provides some Rake tasks to make it easy to preview and deploy the site via gh-pages.

To preview the site, run:

rake site

To release the site to production (don't do this!), run:

rake site_release

The above command will copy the site to the gh-pages branch and push it to GitHub. Once the site is in master it will be easy for people to update it when they update code, making it possible to finally keep code and docs in sync. When a new version is released, the site can also be released with a single command.

Down the road I'd like to pull the actual docs out of the Jekyll site and into a more appropriate format that is then converted into the Jekyll format. But that's another story and will take some time to figure out. For now, this gets us much closer to a workable solution with the new site.

This will also mean the deprecation of the Wiki. When the new site goes live I'd like to update all the Wiki pages (except the list of example sites) to point to the new website pages.

Member

ixti commented Dec 26, 2012

IMHO it's better to call tasks rake preview and rake publish. Or at least rename site to site_preview to be more explicit here.

@tombell tombell commented on an outdated diff Dec 27, 2012

+ puts "Opening in browser..."
+ sh "open http://localhost:4000"
+ end
+
+ # Generate the site in server mode.
+ puts "Running Jekyll..."
+ sh "cd site && jekyll --server"
+end
+
+desc "Commit the local site to the gh-pages branch and deploy"
+task :site_release do
+ # Ensure the gh-pages dir exists so we can generate into it.
+ puts "Checking for gh-pages dir..."
+ unless File.exist?("./gh-pages")
+ puts "No gh-pages directory found. Run the following commands first:"
+ puts " `git clone git@github.com:mojombo/god gh-pages"
@tombell

tombell Dec 27, 2012

Contributor

Might want to update the repo URL ;)

Contributor

tombell commented Dec 27, 2012

Expanding on what @ixti said, maybe rake docs:preview and rake docs:publish.

Member

ixti commented Dec 27, 2012

Also I would like to propose alternative variant of publish task:

Dir.mktmpdir do |tmp|
  cp_r "_site/.", tmp
  Dir.chdir tmp
  system "git init"
  system "git add ."
  message = "Site updated at #{Time.now.utc}"
  system "git commit -m #{message.shellescape}"
  system "git remote add origin git@github.com:ixti/ixti.github.com.git"
  system "git push origin master --force"
end

It was inspired by similar task of Octopress, so credits should go to @imathis :D
In your case you just need to push to gh-pages instead of master.

Extending example above it's possible to avoid tmpdir as well and git init right inside _site dir (removing previously created .git if any. But that's just an idea.

You might want to take a look a full example of this task in my Rakefile or Octopress' Rakefile

@parkr parkr and 1 other commented on an outdated diff Dec 27, 2012

@@ -111,6 +111,52 @@ end
+#############################################################################
+#
+# Site tasks - http://jekyllrb.com
+#
+#############################################################################
+
+desc "Generate and view the site locally"
+task :site do
+ # Yep, it's a hack! Wait a few seconds for the Jekyll site to generate and
+ # then open it in a browser. Someday we can do better than this, I hope.
+ Thread.new do
+ sleep 4
+ puts "Opening in browser..."
+ sh "open http://localhost:4000"
@parkr

parkr Dec 27, 2012

Owner

Are we assuming a Mac OS X dev env? (open)

@ixti

ixti Dec 27, 2012

Member

Looks like :D As Debian GNU/Linux user I would like to propose to have a logic of platform-dependent starters. something like this:

case RUBY_PLATFORM.downcase
when /darwin/ then sh "open http://localhost:4000"
when /linux/ then sh "xdg-open http://localhost:4000 > /dev/null &"
else puts "Don't know how to open browser. DIY & GOTO http://localhost:4000"
end
Owner

parkr commented Dec 27, 2012

👍 to different namespaces than those proposed in the original comment – I really like what @tombell suggested.

Member

ixti commented Dec 27, 2012

A also love variant proposed by @tombell

Contributor

mojombo commented Dec 28, 2012

I've changed the task names now to site:preview and site:publish.

Member

ixti commented Dec 28, 2012

@mojombo Nice! I can provide a patch to allow site:preview become cross-platform (at least linux/bsd/mac) if you want :D

Owner

mattr- commented Dec 29, 2012

👍

Contributor

imathis commented on 88bdb15 Dec 29, 2012

Should the "site" directory be a reference to the Jekyll configuration for destination directory?

Contributor

mojombo commented Dec 29, 2012

Should the "site" directory be a reference to the Jekyll configuration for destination directory?

I'm not sure I understand. What do you mean, exactly?

Contributor

imathis commented Dec 29, 2012

D'oh! I'm sorry, I was confused. I thought this was intended to be a deploy mechanism for users of the gem, not something for deploying the Jekyll.rb site. My mistake, carry on.

Member

ixti commented Dec 29, 2012

@mojombo would be nice if you'll change

sh "open http://localhost:4000"

with this:

require "launchy"
Launchy.open("http://localhost:4000")

Launchy is helper class for launching cross-platform applications in a fire and forget manner.

Contributor

mojombo commented Dec 30, 2012

@ixti I'm not a fan of force pushing over the gh-pages branch for every deploy as your code suggestion would do. I've fixed up the existing one a bit to make it more robust and fix the origin URL error. Only a few people will ever need to run this task, so I don't think the setup is a problem.

Member

ixti commented Dec 30, 2012

@mojombo Well, I tend to agree. It was just a proposal, but your variant looks good to me as well. And absolutely agree about the fact that it's not the most frequent task :D

Contributor

mojombo commented Dec 31, 2012

Thanks for all the comments and suggestions, everyone! I'm merging this in and moving forward with @cobyism's branch.

Contributor

tombell commented Dec 31, 2012

🤘

@mojombo mojombo merged commit 83b3b2a into master Dec 31, 2012

Member

cobyism commented on Rakefile in 83b3b2a Apr 4, 2013

@mojombo Out of interest, is there a reason doing a subtree push thingy wouldn’t be simpler than all this to deploy the site to Pages? I don’t really understand subtrees (which may be reason enough to avoid using this method), but I’ve been doing this to deploy dist folders (created in the primary branch) of yeoman projects to Pages with success, and I’d have thought you could do the exact same thing for Jekyll here, i.e. to push Jekyll’s site dir to gh-pages:

git subtree push --prefix site origin gh-pages

git subtree is not part of git core, you need to add it via modules I think? Well I know this only because I tried unsuccessfully to enable subtree on OSX lion. Point is, since this is a system exec, jekyll shouldn't/can't assume the user has subtree enabled.

Member

cobyism replied Aug 29, 2013

The subtree command is in the contrib directory of git core’s source, which I’m guessing means that they should be available to anyone with an up to date install of Git. I could be wrong (frequently am 😆), but I haven’t ever come across an instance where subtree wasn’t available. Also, considering this is likely to only be run by the maintainers of this repo, I’d say the chance that this isn’t available to them would be slim.

It also doesn’t really matter that much in the grand scheme of things—I was more just curious as to if there was a particular reason it was done this way is all 😄

@jekyllbot jekyllbot locked and limited conversation to collaborators Feb 27, 2017

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.