1## User Documentation for rocksdb.org 2 3This directory will contain the user and feature documentation for RocksDB. The documentation will be hosted on GitHub pages. 4 5### Contributing 6 7See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to add or modify content. 8 9### Run the Site Locally 10 11The requirements for running a GitHub pages site locally is described in [GitHub help](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/#requirements). The steps below summarize these steps. 12 13> If you have run the site before, you can start with step 1 and then move on to step 5. 14 151. Ensure that you are in the `/docs` directory in your local RocksDB clone (i.e., the same directory where this `README.md` exists). The below RubyGems commands, etc. must be run from there. 16 171. Make sure you have Ruby and [RubyGems](https://rubygems.org/) installed. 18 19 > Ruby >= 2.2 is required for the gems. On the latest versions of Mac OS X, Ruby 2.0 is the 20 > default. Use `brew install ruby` (or your preferred upgrade mechanism) to install a newer 21 > version of Ruby for your Mac OS X system. 22 231. Make sure you have [Bundler](http://bundler.io/) installed. 24 25 ``` 26 # may require sudo 27 gem install bundler 28 ``` 291. Install the project's dependencies 30 31 ``` 32 # run this in the 'docs' directory 33 bundle install 34 ``` 35 36 > If you get an error when installing `nokogiri`, you may be running into the problem described 37 > in [this nokogiri issue](https://github.com/sparklemotion/nokogiri/issues/1483). You can 38 > either `brew uninstall xz` (and then `brew install xz` after the bundle is installed) or 39 > `xcode-select --install` (although this may not work if you have already installed command 40 > line tools). 41 421. Run Jekyll's server. 43 44 - On first runs or for structural changes to the documentation (e.g., new sidebar menu item), do a full build. 45 46 ``` 47 bundle exec jekyll serve 48 ``` 49 50 - For content changes only, you can use `--incremental` for faster builds. 51 52 ``` 53 bundle exec jekyll serve --incremental 54 ``` 55 56 > We use `bundle exec` instead of running straight `jekyll` because `bundle exec` will always use the version of Jekyll from our `Gemfile`. Just running `jekyll` will use the system version and may not necessarily be compatible. 57 58 - To run using an actual IP address, you can use `--host=0.0.0.0` 59 60 ``` 61 bundle exec jekyll serve --host=0.0.0.0 62 ``` 63 64 This will allow you to use the IP address associated with your machine in the URL. That way you could share it with other people. 65 66 e.g., on a Mac, you can your IP address with something like `ifconfig | grep "inet " | grep -v 127.0.0.1`. 67 681. Either of commands in the previous step will serve up the site on your local device at http://127.0.0.1:4000/ or http://localhost:4000. 69 70### Updating the Bundle 71 72The site depends on Github Pages and the installed bundle is based on the `github-pages` gem. 73Occasionally that gem might get updated with new or changed functionality. If that is the case, 74you can run: 75 76``` 77bundle update 78``` 79 80to get the latest packages for the installation. 81