blue Group Website Sources

Installing and Building

1. Install node.js and npm, the node package manager.

   • I suggest you use nvm (the node version manager) or install node.js from source. The apt-get packages are fairly old.

2. Join the blue-systems-group group on GitHub and add an SSH key.

3. git clone [email protected]:blue-systems-group/www.git. If this doesn’t work, you probably don’t have a key installed. Return to Step 2.

4. cd www; make install

   • The first time this will take some time since npm install is running and performing some local compilation. Note that you also need ImageMagick installed locally to build the node packages. sudo apt-get install libmagick++-dev does the trick on Ubuntu 14.04.

5. make run, then open localhost:8080 in your browser.

6. When you edit, rerun make and the site will be rebuilt. make check will build and check the site.

7. I suggest a three terminal environment using tmux:

   1. An editing window.

   2. A window to run make or make check.

   3. A window to run make run to serve the sources.

Adding a Profile

1. cd src/people/<your @buffalo email address>

2. Edit bio.adoc which is in AsciiDoc format with a YAML Here’s a bit of mine as an example:

---
name: Geoffrey Challen
role: Assistant Professor
slug: gwa
joined: 2011-08-29
scholar: http://scholar.google.com/citations?user=VS9wzBsAAAAJ&hl=en
linkedin: https://www.linkedin.com/pub/geoffrey-challen/1a/b77/572
spelling_exceptions:
- Chuchu
- Xyz
- Ziz
---
[.lead]
I'm an Assistant Professor at the http://www.buffalo.edu[University at
Buffalo], where I lead the link:/[blue Systems Research Group] and also
direct the http://www.phone-lab.org[PhoneLab].

1. The first part of the file (between the "---"s) is YAML front matter which is used to declare attributes. The rest is AsciiDoc text which defines the page content.

2. The first graph of your bio is used as the snippet on the people page and should be marked [.lead]; the rest appears on your full bio.

3. Please add a square-ish headshot photo in your directory as photo.jpg. Don’t worry too much about the file size or dimensions—the build script automatically creates files that are the right size for the large bootstrap layout. (But don’t add something huge.)

4. Other things to add (see mine for examples):

   • You can add a CV as CV.pdf in your profile directory and it will be automatically linked

   • LinkedIn (linkedin in YAML front matter)

   • Google Scholar (scholar in YAML front matter)

   • GitHub (github in YAML front matter)

Deploying

1. make check runs several sets of build-time checks:

   • Broken links by metalsmith-linkcheck. Broken external links will not fail the build but will generate a warning Broken internal links will.

   • Formatting checks by metalsmith-formatcheck. Format failures will fail the build, but I doubt you’ll be changing the format much.

   • Spelling checks by metalsmith-spellcheck. Spelling failures will halt the build.

   • I maintain all three of these Metalsmith plugins, so if you find bugs let me know.

2. If the build doesn’t complete, fix the problems and rerun make. Don’t push until the build completes.

3. Please check the links_failed.json file if it complains. Sometimes external broken links are a transient problem, but at least check to make sure that you understand what is failing.

4. To add spelling exceptions see the documentation for metalsmith-spellcheck. There are a bunch of ways to do this depending on the word that is being marked as misspelled.

5. Commit your changes to master.

6. Push to master. This triggers remote testing on Travis CI. It runs npm test, which in our case runs make check. If that does not fail, the sources on www.bluegroup.systems will be updated. This sometimes takes a few minutes.

7. If the build fails you should receive an email. The main site will not update. Please fix the problem and push again.

TODOs

• Generate Bibtex references for papers

• GitHub links for projects