This repository contains all the bits and pieces, large and small required to render and deploy Basho's documentation.
This is a Work In Progress! Please let us know if you'd like to help out!
-
Install Hugo by checking out Hugo's Installing page.
-
Clone the repository with:
git clone https://github.com/basho/basho_docs.git cd basho_docs
-
Run Hugo with
hugo server
and wait a couple of seconds for the site to build. -
Play by visiting http://localhost:1313.
Heads-up
When running a local instance of the site, you can't navigate from the splash page (the first page when you navigate to localhost:1313) to the index page of KV, TS, or CS. You will need to manually enter the version in the address bar of your browser. So, for instance, http://localhost:1313/riak/kv/2.2.0/ rather than http://localhost:1313/riak/kv/latest/.
See what we did there?
At this point, any changes you make to the markdown files in the content/
directory will be automatically detected and rendered live in your local browser.
Change some stuff! Have fun!
If you want to modify the content templates that
define how each pages' HTML is generated, modifying the Go Templates
in layouts/_default/
and the partial templates in
layouts/partials/
will also be automatically detected and rendered live in your browser.
Note: Generally, unless you're helping us out with a specific task or project that you've discussed with us, you should not be altering the .js or .css files in this repo.
If you want to mess with the scripts and CSS that this site uses, it's not quite as easy as modifying the HTML.
The scripts and CSS files used to render Hugo content are expected to live in
the static/
directory. We use a lot of Coffee Script and Sass
for our scripting and styling needs, and we convert those files to .js
and
.css
as a pre-render step. We put those .coffee
and .scss
files into the
dynamic/
directory.
Note: For files manually generated, place the source of the generation in a directory parallel to the generated file(s), rooted in
public_src/
. If possible, include a script to generate the output. For example, the uml deployment diagram images instatic/images/redis/
were generated by the .uml files inpublic_src/images/redis/
via the scriptgen_diagrams.sh
w/ the list of source files for generation explicitly listed indiagrams.lst
.
To convert the Coffee and Sass into .js
and .css
files, you'll need to:
-
Install RVM or equivalent.
You might need to restart your shell to get thervm
command to be recognized. -
Install Ruby.
Use the following command:rvm install `cat .ruby-version`
or manually install the current version specified in our .ruby-version and Gemfile files. -
Install Bundler with
gem install bundler
. -
Install the rest of the dependencies with
bundle install
. -
Use Rake to do everything else, like rebuild a copy of everything that should live in
static/
. You can userake build
for that. For a more debug-friendly version of everything, runrake build:debug
.In case you want any changes you make to
.coffee
and.scss
files to be automatically detected and rendered live in your browser, you can runrake watch
.For a list of some of the useful commands, just run
rake
.
Awesome! (We're assuming you said yes. Because you're reading this. And you're awesome.)
This repository operates just like any other open source repo, and only thrives through the efforts of everyone who contributes to it. If you see something wrong, something that could be improved, or something that's simply missing please don't hesitate to:
-
Open Up a New Issue and let us know what you think should change.
-
Find the File You Want to Change and use GitHub's online editor to open a Pull Request right here.
-
Fork This Repository so you can make (and see) your changes locally.
Don't forget to check out our Contributing Guidelines so you
can read up on all our weird little quirks, like how we
don't want you to use <h1>
headers.