/basho_docs

Basho Products Documentation

Primary LanguageCSSOtherNOASSERTION

Basho's Documentation Generation

This repository contains all the bits and pieces, large and small required to render and deploy

http://docs.basho.com/

This is a Work In Progress! Please let us know if you'd like to help out!

Building The HTML Locally

  1. Install Hugo

    Check out Hugo's Installing page.

  2. Clone the Repository

    git clone https://github.com/basho/private_basho_docs.git cd private_basho_docs git checkout hugo/testing

  3. Run Hugo

    hugo server

  4. Play

    http://localhost:1313

No Really, Go Play

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.

Modifying the .js and .css Files

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.

To convert the Coffee and Sass into .js and .css files, you'll need to...

  1. Install RVM or equivalent.

    You might need to restart your shell to get the rvm command to be recognized.

  2. Install Ruby version 2.2.3

    rvm install ruby-2.2.3 or the current version specified in the .ruby-version and Gemfile files.

    If it doesn't match, please open a new issue and let us know this README isn't up to date!

  3. Install Bundler With The ruby-2.2.3 Gem

    gem install bundler

  4. Install the Rest of the Dependencies

    bundle install

  5. Use Rake to do Everything Else

    Like rebuild a copy of everything that should live in static/. rake build

    Or output a more debug-friendly version of everything? rake build:debug

    Or maybe you want any changes you make to .coffee and .scss files to be automatically detected, and rendered live in your browser? rake watch

For a list of some of the useful commands, just run,

`rake`

Would You Like to Contribute?

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.