The 18F Hub is a Jekyll-based documentation platform that aims to help 18F and other development teams organize and easily share their information, and to enable easy exploration of the connections between team members, projects, and skill sets. It aims to serve as the go-to place for all of a team's working information, whether that information is integrated into the Hub directly or provided as links to other sources. It also serves as a lightweight tool that other teams can experiment with and deploy with a minimum of setup.
See the 18F blog post announcing the Hub for more details about the vision behind the Hub and the goals it aims to achieve.
The main Git repository is https://github.com/18F/hub and the primary maintainer (for now) is @mbland. The goal is to eventually hand ownership over to the Documentation Working Group, or to the 18F team as a whole.
It takes less than a minute to set up a hands-on demo, which we hope will inspire other teams to develop their own Hubs, publish snippets, and organize working groups/guilds/grouplets.
You will need Ruby ( > version 2.0 is a good idea). You may also consider using a Ruby version manager such as rbenv to help ensure that Ruby version upgrades don't mean all your gems will need to be rebuilt.
To run your own local instance:
$ git clone git@github.com:18F/hub.git
$ cd hub
$ gem install bundler
$ bundle
$ bundle exec jekyll serve
The internal 18F Hub is hosted at https://hub.18f.us/ and the public Hub staging area is hosted at https://hub.18f.us/hub.
18F team members will want to initialize the 18F/data-private and 18F/hub-pages-private submodules after cloning:
# Initialize the _data/private and pages/private submodules
$ git submodule init
$ git submodule update --remote
By default, bundle exec jekyll serve will build the site with data from _data/private if it is available. Not all data in _data/private is actually private, but data that should not be shared outside the team is marked by nesting it within private: attributes. To build in "public mode" so that information marked as private doesn't appear in the generated site:
$ bundle exec jekyll serve --config _config.yml,_config_public.yml
See the Data README for instructions on how to import data into _data/public for deployment to the Public Hub.
If you have Vagrant and Ansible installed, you can launch a local development server running Nginx by running vagrant up. The server will be accessible at localhost:8080 for the internal version, and localhost:8080/hub for the public version.
For the internal version of the site, the dev server will default to setting the Nginx $authenticated_user variable (used by _layouts/bare.html) to the authenticated_user value in deploy/ansible/playbook.yml. You can also change this for a single page by adding ?user=[AUTHENTICATED_USER] to the URL.
In addition to this README, there is also:
- Deployment README - DevOps details: publishing the generated site; AWS; Nginx; SSL; Google Auth Proxy
- Plugins README - Development details: data import and joining; canonicalization; cross-referencing; page generation
- Data README - Details regarding the organization and processing of data.
- Fork the repo ( https://github.com/18F/hub/fork )
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
Feel free to ping @mbland with any questions you may have, especially if the current documentation should've addressed your needs, but didn't.
This project is in the worldwide public domain. As stated in CONTRIBUTING:
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.