Overview

The following guide is an overview on how to update the site for each particular element. Each page on this site is given by a combination of markdown files, .yaml files, and Jupyter notebooks. These files are converted to HTML using Jekyll, a static web page generator. The site is tested on Travis CI using HTMLProofer, which automatically checks the site for errors. The .travis.yml file contains everything required to build the site. Note that if the instructions below and the .travis.yml are not synced then the build outlined in the travis.yml should be used. The main site is hosted on pages.nist.gov, which provides the build.log for the Jekyll build.

Different aspects of this site can be edited using Google Forms, GitHub, or on your local machine. The list below gives which method should be used for various types of changes. Many of these tasks require that you have an account on GitHub.

Update directly on GitHub

• Add yourself to the community page
• Add a new phase field code
• Add a new workshop
• Add a new page

Update on your local machine

• How to build and view the site locally
• Update and build the Hexbin (hexagonal tiles of images on the homepage)
• Add a Jupyter notebook
• Add a new benchmark problem
• Test the HTML output

Detailed instructions for each of aspects of the site are given in the following sections.

Update Directly on GitHub

Several common tasks can be accomplished on GitHub by editing files in-place. Doing so will automatically fork the repository to your GitHub account and submit a pull request to update the master GitHub repository with your content.

Update the Community Page

To add a new entry to the communtiy page edit the community.yaml file. The following fields need to be included for each entry.

- name: Your name
  text: A biographical sketch
  email: Your email
  home: Link to your home page
  github_id: Your Github ID
  twitter: Your Twitter handle
  avatar: Link to your image

Please also add other social media links beyond GitHub and Twitter that you’d like to include as well.

Add a New Phase Field Code

To add a new phase field code to the list of codes on the front page, follow the submission instructions on the main site. Jekyll will automatically rebuild the site after codes.yaml is edited.

Add a New Workshop

To add a new workshop edit the workshop.yaml file. The following fields need to be included for each entry.

- name: "Phase Field Methods Workshop I"
  date: "Jan 9-10, 2015"
  href: http://planitpurple.northwestern.edu/event/474167/xJDsFEfb
  number: 1
  contact: mailto:daniel.wheeler@nist.gov
  description: >-
    Workshop held at Northwestern University to discuss code
    collaboration in phase field modelling.
  icon_links:
    - name: contact organizer
      type: email
      href: "mailto:daniel.wheeler@nist.gov?subject=First Phase Field Methods Workshop"
    - name: Download PDF
      type: file_download
      href: "/pfhub/docs/CHiMaD_PhaseFieldWorkshop.pdf"

For each of the icon_links, the type field must correspond to a Materialize icon.

Add a New Page

To add a new page create the page as a Markdown file directly on GitHub. For example, click “Create new file” on GitHub called my-page.md and add the contents

---
layout: basic
---

# My Phase Field Page

Something about phase field ...

Submit a pull request on GitHub and this page will appear under .../pfhub/my-page after the pull-request is merged.

Update on Your Local Machine

Some tasks involve adding new files or rebuilding existing ones. These are best done on your local machine, on a clone of your fork of the master GitHub repository. You are encouraged to serve as local version of the site for testing before pushing your commitsand issuing a pull request.

Build and Serve the Site

The site uses the Jekyll static web site generator. To build the environment required to serve the site, use the following commands.

$ sudo apt-get update
$ sudo apt-get install ruby nodejs
$ sudo gem install jekyll jekyll-coffeescript

Then clone your fork of the GitHub repository.

$ git clone https://github.com/your_GitHub_account/pfhub.git
$ cd pfhub
$ jekyll serve

At this point Jekyll should be serving the site. Go to http://localhost:4000/pfhub/ or the link Jekyll provides on the terminal, to view the site.

Update and Build the Hexbin

To build the Hexbin, the tiled hexagonal images on the homepage, a Python environment is required. To setup the environment use Conda.

$ wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh
$ bash miniconda.sh -b -p $HOME/miniconda
$ export PATH="$HOME/miniconda/bin:$PATH"
$ conda update conda
$ conda create -n test-environment python=3

Create an environment with the required packages

$ source activate test-environment
$ conda install -n test-environment pillow numpy

Update the data in the hexbin.yaml file. The following format is used for each entry.

- image: http://www.mem.drexel.edu/ysun/files/density.png
  url: http://www.mem.drexel.edu/ysun/Solidification.htm
  title: Solidification Simulation
  description: >-
    Phase-Field Simulation of Solidification (Collaborator:
    Prof. Christoph Beckermann, University of Iowa) The `url` field is the page that describes the image or the work associated with the image.  After updating rebuild the Hexbin.

$ make hexbin

Jekyll should automatically update the site.

Add a Jupyter Notebook

The benchmark specifications are built using Jupyter Notebooks. To render the notebooks as HTML, first generate the Python environment outlined above, and then install Jupyter.

$ source activate test-environment
$ conda install -n test-environment jupyter

Make a new notebook or edit an existing one and then rebuild the notebook HTML.

$ make notebooks

This should automatically generate the HTML and Jekyll will render it on the site. For example, a notebook in the base directory named my_notebook.ipynb will be rendered at http://localhost:4000/pfhub/my_notebook.ipynb.

Add a New Benchmark Problem

To add a new benchmark problem include a notebook describing the new problem and then link to it via the benchmarks.yaml file with the following fields.

- title: Spinodal Decomposition
  url: "benchmarks/benchmark1.ipynb/"
  description: Test the diffusion of a solute in a matrix.
  image: http://www.comsol.com/model/image/2054/big.png

Testing

The site can be tested at the command line using HTMLProofer. This validates the generated HTML output. First install HTMLProofer.

$ sudo gem install html-proofer

Make fresh builds of all the notebooks to check that they can be built.

$ find . -name "*.ipynb" -type f -not -path "*/.ipynb_checkpoints/*" -exec touch {} \;
$ make notebooks

Make a fresh Hexbin to check its build process.

$ touch _data/hexbin.yaml
$ make hexbin

Use HTMLProofer to check the site.

$ jekyll build -d ./_site/pfhub && htmlproofer --allow-hash-href --empty-alt-ignore --checks-to-ignore ImageCheck ./_site

Note that the images are not checked for valid HTML and for links as the images that are auto-generated by Jupyter which seems to break HTML guidelines (no alt tag for example). Also note that the rendered HTML needs to be written to ./_site/pfhub rather than /_site for HTMLProofer to check the internal links correctly.