Add README file.
This commit is contained in:
Alex Wood
parent
fbcb8ba5f2
commit
0248ec0cf6
|
|
@ -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`
|
||||
|
|
@ -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.
|
||||
|
|
@ -19,7 +19,7 @@ exclude:
|
|||
- package.json
|
||||
- package-lock.json
|
||||
- node_modules
|
||||
- CONTRIBUTING.md
|
||||
- README.md
|
||||
- Gruntfile.js
|
||||
- .eslintrc.json
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue