Last week, eagle-eyed observers should have seen that a new website was built and uploaded to the crossbridge project's gh-pages branch. This post will explain how to make changes and how the website refreshes work.
The contents of the website is built from the main repository contents using a ruby script. The script currently copies README.html and the html and support files from the docs/ folder from the repository. It does a little DOM-handling to take only the contents from the pages and add them to the new design. Any pages added to the docs/ folders would be added automagically when updated. Other files elsewhere would need to be added to the
@files_list variable. Lastly, it uses the README.md file as the website index, making a good pair with the repository landing page.
Before deploying, you have to prepare a small workspace.
- Cloning the website repository.
git clone firstname.lastname@example.org:crossbridge-community/crossbridge.io-builder.git
git submodule init ; git submodule update
- Having a checkout of crossbridge in the same directory. I did not use a submodule as crossbrige is an heavy repository. I recommend cloning it locally if possible. Otherwise, a shallow clone would do the trick.
git clone --depth 1 https://github.com/crossbridge-community/crossbridge.git crossbridge
We'll assume that the website is always synchronized to the master branch
git checkout master
- We'll also need a clone of the gh-pages branch of the main crossbridge repository. For this one, a shallow clone works also, but you should always clone it from the main repository, as a shallow clone does not weigh much for that branch.
git clone -b gh-pages --depth 1 email@example.com:crossbridge-community/crossbridge.git gh-pages
- Once all done, prepare the build environment using
- A temporary step has to be done manually. You will need a release package of crossbridge and copy the apidocs folder to the source folder.
cp -ar $PATH_TO_RELEASE/docs/apidocs source/docs/
Once this is done you're ready to update the site and check the changes locally. Please verify your changes locally before deploying changes. All changes have to be done to the main crossbridge repository, the
crossbridge.io-builder only contains what's needed to update the website from that repository.
- Fetch the "website contents" using the update script.
bundle exec ruby update_site_from_repo.rb
- Use middleman to serve a local instance of the site
bundle exec middleman
- Go to the URL specified in the console, it should be something like http://localhost:4567/.
- Verify the contents matches the expected outcome of the changes.
Once this is all done, I suggest committing the changes you made to the crossbridge repo, then doing the pull-merge-push dance.
Next, to deploy the website, I have made a small script that should always work as long as you have write access to the crossbridge repository.
The deploy script should have enough logic right now to fail early in case something is not right in the previous steps. If the deploy script does something unexpected and "breaks" the site, assume it is a bug and report it here please.