Home

Pages

Lay out each page as an index.md within its folder:

/niem-releases/index.md

If you don't do it this way, links to a page can work inconsistently. Otherwise, we've seen .../niem-releases/ fail while .../niem-releases works. It has always worked as expected when arranged as an index in a folder.

How to collaborate

The production website (http://niem.github.io/) is built from the latest commit to the NIEM repo's master branch. Only push content that is ready for distribution on the main website.

Before updating the main site, development and testing should be done on your local machine and on your fork of the NIEM repo.

Pull requests are welcome. Please merge the latest master commit into your commit, so that it can be easily merged.

Stage changes locally

You can build the site locally to test changes as you work before pushing them to GitHub.

Run the following command:

bundle exec jekyll serve --baseurl '' --incremental

Once finished, a localhost URL will be logged to the terminal with your updates. The "incremental" flag in the command above will cause your local pages to update when you save a file.

See https://jekyllrb.com/docs/usage/ and https://jekyllrb.com/docs/ for more.

Stage changes to your local fork

Publishing changes to your local fork will let you stage changes so that you and others can see the changes before updating the main site.

Enable GitHub Pages

Set up your fork to build the website off of the "gh-pages" branch. This branch will be used rather than the "master" branch as used by the main site so that development changes can be tested from any branch before merging updates back into master.

• In your forked repo on GitHub, go to Settings
• Click on "Pages" in the sidebar
• Select the gh-pages branch as the source.

Update your gh-pages branch

The gh-pages branch can be used like a pointer to the branch that you currently want to test. You can set it to point to a development branch for one update, to your master branch for another update, and so on. Make sure your updates are maintained on a separate, persistent branch before moving your gh-pages branch to avoid losing your work.

To push your local changes in one branch directly to the gh-pages branch of your forked GitHub repo:

git push -f upstream branch:gh-pages

Where upstream is the name locally assigned to your GitHub repo and branch is the name of the branch you wish to publish. (Use git remote -v to see remote repo names.)

The -f flag forces the commit without doing a merge. This lets you publish alternate branches as needed (e.g., dev-json, dev-training, dev-newfeature) without having to merge them before they are ready.

Go to https://USERNAME.github.io/NIEM.github.io/ to see your site. Note that it may take about 10 minutes for the site to update.

Merge before you push

When collaborating with others on a branch, please merge other people's commits into your branch before pushing your commits to your fork. This will ensure that others can integrate your changes into their own work without excessive work.

Local build issues?

If you have trouble building the site locally with jekyll serve, check the following:

• Run bundle install to make sure you have the right versions of the dependencies installed.

• Liquid Exception error after running bundle exec jekyll serve
  Check that your version of bundler (run bundler -v from the command line) is the same as the one listed at the bottom of the Gemfile.lock file.