Fixes #560: Adds how-to README for docs (#561)

* Added how-to README.md file to docs/ directory; and referenced
the docs directory in the main README.md.

* Made requested changes from jgthms.

* made requested changes

diff --git a/README.md b/README.md
index 5e47a43ea31b8464ea23761bf61edd92f66f7230..1ddc88b4ee516f4215c1daa3ef7de910e9399aa8 100644 (file)
--- a/README.md
+++ b/README.md
@@ -49,6 +49,12 @@ Bulma uses [autoprefixer](https://github.com/postcss/autoprefixer) to make (most
 * Opera
 * Safari
 
+## Documentation
+
+The documentation resides in the [docs](docs) directory, and is built with the Ruby-based [Jekyll](https://jekyllrb.com/) tool.
+
+Browse the [online documentation here.](http://bulma.io/documentation/overview/start/)
+
 ## Related projects
 
 * Bulma with Attribute Modules: https://github.com/j5bot/bulma-attribute-selectors

diff --git a/docs/README.md b/docs/README.md
new file mode 100644 (file)
index 0000000..5fe0de2
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,19 @@
+## Building the documentation
+
+The documentation HTML is produced with the Ruby-based `jekyll` tool.
+
+1. Make sure Ruby 2.x is installed.
+2. `gem install jekyll`
+
+## Viewing the documentation locally
+
+Then to view the documentation in your local checkout:
+
+1. Before you begin, cd into `docs/` directory, and `cp _config.yml _config.local.yml`. Then edit `_config.local.yml` and change the `url:` value to `http://localhost:4000`. This local config file will be ignored by git. 
+1. In a separate shell session, `cd` to the `docs/` directory, and do:
+```
+jekyll serve --incremental --config _config.local.yml
+```
+This will start an HTTP server at `http://localhost:4000/` that serves the docs built in the `_site` directory; and anytime the docs are rebuilt by you, it will serve the docs site on the fly.
+2. In your main shell session where you develop, if you change anything in `docs/` the jekyll server will rebuild those on the fly. But if you change anything about the Bulma SASS or CSS, you need to do `npm run start-docs` to build the docs' CSS before you will see it in the browser. The process running `jekyll serve` will pick up the new CSS automatically.
+