diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 7c8dc4d..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,76 +0,0 @@ -# How to Contribute - -The "rules" of Zargon are not set in stone. We want them to be sourced by our community. To add / remove / modify rules, please submit them via a new Issue or PR. - -You can use these handy links to help get you started - -- [Add a rule](https://github.com/zargon-now/zargon-now.github.io/issues/new?template=add_rule.md) -- [Change a rule](https://github.com/zargon-now/zargon-now.github.io/issues/new?template=change_rule.md) -- [Remove a rule](https://github.com/zargon-now/zargon-now.github.io/issues/new?template=remove_rule.md) - -If you are comfortable with development, you can also send a [pull request](http://help.github.com/pull-requests/) with the change. We recommend creating an new issue with your pull request so that discussion on the change can happen. - -# Setting up a developer environment - -The site is run using [Jekyll](https://jekyllrb.com/) and is pretty easy to figure out. To start local development you'll need to install Jekyll, bundler and install your dependencies - -1. ```bash - gem install jekyll bundler - ``` -2. ```bash - bundler install - ``` -3. ```bash - bundle exec jekyll serve - ``` - -This will serve up the page at `localhost:4000` and any changes to the files you make will be shown "live" at that site. - -## Modifying / adding Javascript and CSS - -Javascript and CSS libraries are managed via [Bower](https://bower.io/) and [Grunt](https://gruntjs.com/). You will need to have `npm` available and have `bower` and `grunt-cli` installed globally. - -1. Add new assets using `bower install \[asset\] --save` -2. Update the assets by running `npm run build` - -## Folder structure - -### \_data - -This folder contains the data that drives the site - -- `rules.json` - This file defines the orders of the rules. To add a new section, add the file to `_data/all_rules/sectionname.json` and add `sectionname` to the `orders` entry -- `all_rules` - This folder contains all of the rules. - - `games.json` - Rules surrounding playing games - - `membership.json` - Rules around membership in Zargon - -To add a new rule set, create a file in `_data/all_rules/sectionname.json` with the following format - -```javascript -{ - "title": "A New Rule Set", - "rules": [ - { "text": "This will be the first rule" }, - { "text": "This will be the second rule" } - ] -} -``` - -### \_includes - -This folder contains template files used in other pages - -- `footer.html` - The footer -- `navbar.html` - The global navbar. Not currently used. -- `rules.html` - The rules section -- `style.html` - The global style sheet - -### \_layouts - -This folder contains the layouts used in other pages - -- `page.html` - The general page layout - -### assets - -The static assets used in the site. **Note**: This should not be manually added to but instead generated using `grunt` \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..561ba74 --- /dev/null +++ b/README.md @@ -0,0 +1,54 @@ +# Getting Started + +* Make sure you have Ruby, Node.js, and NPM installed. You need to install + `nodejs-grunt-cli`. +* `gem install bundler` +* `bundle install` +* `npm install` + +## What is This Node.JS Stuff? + +It's a way for us to manage our asset dependencies (namely, our CSS framework +and JavaScript framework). If you're just developing content for the site, you +don't need to worry about it. + +For the asset libraries, we're using [Bower](https://bower.io/) which is invoked +via [Grunt](https://gruntjs.com/). If you need to update the libraries, you'll +make a change to the `bower.json` file and change the version number. Then run +`grunt`. The default Grunt task will wipe the old dependencies and install the +new ones under `assets/vendor` and `bower_components`. The `assets/vendor` +files can be used directly. The files under `bower_components` are primarily +for pre-processing and **should not** be pulled in directly. For example, the +`zargon.scss` file includes a bunch of the Bulma Sass so we can use their mixins +and variables if we want. You'll notice in `_config.yaml` that we're telling +Jekyll to place `bower_components/bulma` on the Sass load path. + +## This Seems Overly Complicated! + +Yes. But apparently this is how The Internet has decided to do web development +now. We could do this via a Rakefile but the only Rake integration I could find +bolted a Rails-style asset pipeline onto Jekyll which is just as complicated (if +not more so). + +# Writing Content + +Create a file with a `.md` suffix. At the top add + +``` +--- +title: My Title +layout: standard-page +--- +``` + +That meta-data will tell Jekyll the title of your page and the page layout to +use. Then just write your content using Markdown syntax. + +# Previewing the Site + +Run `bundle exec jekyll serve --livereload`. Jekyll will render the site (into +the `_site` directory) and start a webserver on localhost's port 4000. You can +point a browser there and get a preview of the site. As a bonus the +`--livereload` argument will watch the directory for changes. On any change, +the site will be re-rendered and Jekyll will notify your browser to refresh +itself. diff --git a/_config.yml b/_config.yml index 56aaa9e..c053d9a 100644 --- a/_config.yml +++ b/_config.yml @@ -19,7 +19,7 @@ exclude: - package.json - package-lock.json - node_modules - - CONTRIBUTING.md + - README.md - Gruntfile.js - .eslintrc.json