Browse Source

Add README file.

pull/4/head
Alex Wood 1 year ago
parent
commit
0248ec0cf6
3 changed files with 55 additions and 77 deletions
  1. +0
    -76
      CONTRIBUTING.md
  2. +54
    -0
      README.md
  3. +1
    -1
      _config.yml

+ 0
- 76
CONTRIBUTING.md View File

@@ -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`

+ 54
- 0
README.md View File

@@ -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.

+ 1
- 1
_config.yml View File

@@ -19,7 +19,7 @@ exclude:
- package.json
- package-lock.json
- node_modules
- CONTRIBUTING.md
- README.md
- Gruntfile.js
- .eslintrc.json



Loading…
Cancel
Save