Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/railsapps/rails-windows.github.io

Content for the Rails for Windows web site.
https://github.com/railsapps/rails-windows.github.io

Last synced: about 1 year ago
JSON representation

Content for the Rails for Windows web site.

Awesome Lists containing this project

README 

          
h1. The Rails for Windows Website



This repository contains the static web pages for the site at "http://rails-windows.github.io":http://rails-windows.github.io.



This is the source repository for a community website featuring instructions for setting up Ruby on Rails on Windows. All contributions are screened by the project maintainers to prevent spam.



h2. Contributing



Anyone with a GitHub account can add items to the site.



There are two ways to add items. You can open a GitHub issue or edit the GitHub wiki.



h4. "Create a GitHub issue":https://github.com/rails-windows/rails-windows.github.io/issues



Create a GitHub issue to suggest a resource. The project maintainers periodically review issues and update the site.



h4. "Edit the GitHub wiki":https://github.com/rails-windows/rails-windows.github.io/wiki



You can help out by editing the pages directly in the GitHub wiki.



After editing a page, create a GitHub issue to let the project maintainers know your addition is ready for review.



All contributions are screened before the website is updated.



h2. Project Maintainers



Ask for commit privileges if you'd like to contribute as a project maintainer.



With commit privileges, you can clone the wiki and edit locally. Using your favorite text editor is easier than editing the wiki online. Also, you'll need a local copy of the repository to generate the web site.



h3. Publishing Workflow



There are two repositories:



* the site repo at "https://github.com/rails-windows/rails-windows.github.io":https://github.com/rails-windows/rails-windows.github.io (for the static web pages)

* the wiki repo at "https://github.com/rails-windows/rails-windows.github.io/wiki":https://github.com/rails-windows/rails-windows.github.io/wiki (for the wiki pages)



GitHub automatically makes any HTML (and CSS and JavaScript) files available as a project website when a repository is present with the name rails-windows.github.io. All we have to do to publish the website is commit HTML files to the repository and push to GitHub.



Using the wiki as a source for the pages gives us two benefits:



* anyone with a GitHub account can contribute by editing the wiki

* we can use Markdown or Textile (instead of HTML) to format the content



To publish the site, we clone the wiki pages, make any edits locally, and then run the "gollum-site":https://github.com/dreverri/gollum-site gem to generate static web pages from the wiki. Commit and push the static pages and GitHub automatically updates the site. Typically it takes ten minutes for GitHub to refresh the site.



h3. Requirements



The "gollum-site":https://github.com/dreverri/gollum-site gem  requires Ruby 1.9.3 (it doesn't yet work for Ruby 2.0.)



* WINDOWS: Use "URU":https://bitbucket.org/jonforums/uru to install Ruby 1.9.3 and create a project-specific gemset.

* LINUX:  Use "RVM":https://rvm.io/ to install Ruby 1.9.3 and create a project-specific gemset.



h3. Gems



The gollum-site gem requires Nokogiri.




$ gem install nokogiri




The gollum-site gem requires the RedCloth gem to support "Textile":http://www.textism.com/tools/textile/ markup. To avoid an issue with the current RedCloth version 4.2.9, install an earlier version.




$ gem install RedCloth --version '4.2.8'




You may also need the Thor gem for a script that modifies the HTML files.




$ gem install thor




Install the gollum-site gem.




$ gem install gollum-site




h3. Workspace Troubleshooting on Windows



Some patch fixes will need to be enabled in order to publish to the wiki from Windows




REDCLOTH gem 4.2.8




In order to remove RedCloth warnings regarding obsolete and deprecated config on redcloth.rb:10 do the following:




#Edit (ruby193\lib\ruby\gems\1.9.1\gems\RedCloth-4.2.8\lib\redcloth.rb:10)

conf = Object.const_get(defined?(RbConfig) ? :RbConfig : :Config)::CONFIG

prefix = conf['arch'] =~ /mswin|mingw/ ? "#{conf['MAJOR']}.#{conf['MINOR']}/" : ''





BLANKSLATE gem 3.1.2




In order to remove Blankstate warnings do the following:




#Edit (ruby193\lib\ruby\gems\1.9.1\gems\blankslate-3.1.2\lib\blankslate.rb:46)

def hide(name)

  # ADDED STATEMENT BELOW

  v, $VERBOSE = $VERBOSE, nil

  if instance_methods.include?(name._blankslate_as_name) and

    name !~ /^(__|instance_eval$)/

    @hidden_methods ||= {}

    @hidden_methods[name.to_sym] = instance_method(name)

    undef_method name

  end

  # ALSO ADDED STATEMENT BELOW

  $VERBOSE = v

#end





Gollum




Gollum-site generates 'spawn can't convert nil into string' errors.  This stems from grit 2.4.2 requiring spawn-posix which does not work on windows.  Do the following to fix this error:




C:\> gem install grit -v '2.3.0'




Edit the gollum gemspec and change the grit dependency in gollum-1.4.3 or the gem version you are using.




s.add_dependency('grit', "2.3.0") # which removes spawn-posix requirement




Build and install the new gollum gem.




gem build gollum.gemspec

gem install gollum-1.4.3.gem




These three fixes should then allow you to publish from Windows.



h3. Clone the Repos



Create a directory for the project and clone the repositories.




$ mkdir ~/rails-windows

$ cd ~/rails-windows

$ git clone git@github.com:rails-windows/rails-windows.github.io.git

$ git clone git@github.com:rails-windows/rails-windows.github.io.wiki.git




h3. Edit the Content



Make sure you are in the git "master" branch. Edit the wiki pages and commit any changes.




$ cd rails-windows.github.io.wiki

$ git checkout master

# edit wiki pages with a text editor

$ git add -A

$ git commit -m "update"




h3. Change the Layout and Design



To change the layout and design, edit the *_Layout.html* file and change any CSS and Javascript files in the rails-windows.github.io.wiki repository. Then commit any changes.




# edit the *_Layout.html* file with a text editor

# edit the *css/screen.css* file with a text editor

$ git add -A

$ git commit -m "update layout"




h3. Generate Static Web Pages



When you are ready to generate the static pages, use the gollum-site gem to generate the static web pages in the wiki repo. Gollum-site has a built-in web server if you want to view the site locally before committing and publishing to GitHub.




$ gollum-site generate ## to generate static webpages in "./_site" folder

$ gollum-site serve ## to view the static site at http://localhost:8000




h3. Publish to GitHub



Copy the generated @_site@ directory to the site repo. Rename the @Home.html@ page as @index.html@. Commit the changes and push the repo up to GitHub. To commit the generated web pages, you'll need repository read+write permission as an organization team member. GitHub will automatically publish the updated site in ten minutes or less.



h4. Publish from Windows (using PowerShell)




# =============================================================================================

# To run this in Windows PowerShell do the following

# Visit https://github.com/dahlbyk/posh-git for instructions

# Clone the posh-git locally

# From the posh-git repository run .\install.ps1

# git clone git@github.com:dahlbyk/posh-git.git

# you can modify the default profile being loaded by posh-git by going to the cloned directory

#

# Set the environment variables below to the workspace\directory\ you cloned the repos to.

# =============================================================================================



# START OF SCRIPT



# Clear and stop other PowerShell Instances

clear

echo "__________________________________________________________________"

echo "===> Stopping other PowerShell Instances"

Get-Process Powershell  | Where-Object { $_.ID -ne $pid } | Stop-Process



# Use URU to switch to the appropriate Ruby version and set working Variables

echo "__________________________________________________________________"

echo "===> Switching to Ruby 1.9.3 and configuring environment"

# Switch to Ruby 1.9.3 p 484

uru 193p484

# Set some working environment variables

$myEnvironment = "C:\Development\rails4stack\rails-windows"

$wiki = "C:\Development\rails4stack\rails-windows\rails-windows.github.io.wiki"

$fullsite = "C:\Development\rails4stack\rails-windows\rails-windows.github.io.wiki\_site\*"

$site = "C:\Development\rails4stack\rails-windows\rails-windows.github.io.wiki\_site"

$destination = "C:\Development\rails4stack\rails-windows\rails-windows.github.io"



# Perform some cleanup, if necessary

echo "__________________________________________________________________"

echo "===> Checking cleanup routines"

$_siteInWiki = Test-Path $site

if ($_siteInWiki){

  echo "===> Cleaning up.. Deleting io.wiki\_site"

  Remove-Item -Recurse -Force $site

} else {

  echo "===> Cleanup not necessary."

}



# Start the Gollum site generator

echo "__________________________________________________________________"

echo "===> Running Gollum-site generator in wiki"

cd $wiki

gollum-site generate

echo "... GENERATED _site";



# Copy _site to .io and overwrite all files

echo "__________________________________________________________________"

echo "===> Copying " $fullsite

echo "===> -TO-"

echo "===> Copying " $destination

Copy-Item $fullsite $destination -Recurse -Force



# Delete old _site directory in Wiki

echo "__________________________________________________________________"

echo "===> Deleting " $site

Remove-Item -Recurse -Force $site



# Push to Github.io.wiki

echo "__________________________________________________________________"

echo "===> COMMITTING to Github.io.wiki"

echo "_____________________USER INPUT REQUIRED!_________________________"

$commit = Read-Host 'Please type your commit message...'

git add -A

git commit -m $commit

git push origin master

echo "... FINISHED Pushing to github.io.wiki";



# Repush Home to Index

echo "__________________________________________________________________"

echo "===> Replace index.html with Home.html"

cd $destination

del index.html

move-item Home.html index.html



# Push to Github.io

echo "__________________________________________________________________"

echo "===> COMMITTING to Github.io"

git add -A

git commit -am $commit

git push origin master

echo "... FINISHED Pushing to github.io";

# END OF SCRIPT




Run the script as an alternative to entering commands manually by starting PowerShell and running the following commands:




PS C:\> cd ~/workspace/rails-windows/rails-windows.github.io.wiki

PS C:\> publish.ps1




h4. Publish from Linux




$ cp -R _site/* ../rails-windows.github.io

$ rm -rf _site/

$ cd ../rails-windows.github.io

$ mv Home.html index.html

$ git add -A

$ git commit -am "update website"

$ git push origin master




See the updated site at "http://rails-windows.github.io":http://rails-windows.github.io.



h4. Script to Publish from Linux



The rails-windows.github.io.wiki repository contains a shell script to automate the publishing process.




#!/usr/bin/env bash



echo "publishing to the rails-windows.github.io site"

cd ~/workspace/rails-windows/rails-windows.github.io.wiki

gollum-site generate

echo "GENERATED";

cp -R _site/* ../rails-windows.github.io

rm -rf _site/

cd ../rails-windows.github.io

mv Home.html index.html

echo "COMMITTING";

git add -A

git commit -am "update website"

git push origin master

echo "FINISHED";

exit 0




Run the script as an alternative to entering commands manually.




$ cd ~/workspace/rails-windows/rails-windows.github.io.wiki

$ ./publish.sh




h2. Why?



Here are the goals I had in mind when I set up the project:



* I wanted to set up a process where anyone with a GitHub account could contribute but project maintainers screened the contributions before publishing the site.



* I wanted to use GitHub's capability for hosting the site. The hosting is free and the wiki is familiar to GitHub users. I didn't want to deploy a dedicated CMS or use a wiki hosted elsewhere.



* I'd like any GitHub user to be able to add to the site (or make corrections) by editing the repository's wiki pages directly.



* I like being able to edit the wiki pages locally using Markdown or Textile markup. I use the same text editor and workflow that I use for maintaining code.



* On its own, the GitHub wiki does not provide everything I wanted for the project website. I wanted to improve the layout and design to make the site more attractive and useful. I wanted to add Javascript for a commenting system as well as a Google Analytics tracking script.



h3. Alternative Approaches



I looked at several "static website generators":http://nanoc.stoneship.org/docs/1-introduction/, including "Jekyll":https://github.com/mojombo/jekyll, and decided "gollum-site":https://github.com/dreverri/gollum-site most closely fit my requirements.



"Jekyll":https://github.com/mojombo/jekyll generates static pages from markup but it's more complex and better suited to publishing a blog.



I looked at "Smeagol":https://github.com/benbjohnson/smeagol. It is a server that hosts and renders a "Gollum":http://github.com/github/gollum wiki (such as GitHub wiki pages). It requires installation as an app on a hosting site that runs Ruby. It would require maintaining a server and would not allow the site to be hosted on a GitHub subdomain.



h2. Issues



Improvements or corrections to the web site? You can edit the "wiki pages":https://github.com/rails-windows/rails-windows.github.io/wiki directly.



h2. Credits



Joel Dezenzio wrote the guide to Rails for Windows.



Daniel Kehoe set up the organization website.



You are welcome to volunteer as a project maintainer.



h2. MIT License



"MIT License":http://www.opensource.org/licenses/mit-license



!https://cruel-carlota.pagodabox.com/429c5f252529a678207c41bd32ce4675(githalytics.com alpha)!