Welcome to Sensu Docs! This repository is the new home of all Sensu-related documentation and we appreciate your help in maintaining it. You can view the live site at docs.sensu.io.
Contribution was too complicated when working with the now-deprecated sensu-docs-legacy project. Building it depended on proprietary website code. In addition to making the build independent of our marketing website, this new project gives us:
- Much faster rendering times
- Versioned documentation per project all in one place
- Easier contribution experience running Hugo locally
- Full-text search 😍
- Uchiwa links to the existing website
- There is no Extensions documentation at this time
- Plugin documentation is very out of date. Help fix that by participating in this issue
- Sensu Core 2.0 documentation will be partially missing until the Beta milestone is reached
This README is focused on helping you get started with the sensu-docs project as a whole. For detail on formatting, layouts and other aspects of adding to or modifying content, please see our project wiki.
Unlike the old sensu-docs project, this site can be run locally with Hugo. There are some new steps to learn, but don't worry, we've documented how to do so (and some common troubleshooting if you need it):
This project uses git submodules to manage themes. If you have git 1.6.5 or later, you can clone this project and checkout submodules in one command:
git clone --recursive https://github.com/sensu/sensu-docs.git sensu-docs
If you cloned this repository without the --recursive flag, you can manually pull in the theme submodule:
cd sensu-docs ; git submodule update --init --recursive
This project uses Yarn to manage dependencies and the build process. For information on installing yarn, view their documentation.
After installing yarn we suggest that you test the build of the site in your local environment:
yarn
Yarn will install and run Hugo to render the site into the public directory.
This is the same build process used by TravisCI to test changes. If this command produces any errors, please open an issue.
If the site builds successfully, you can run the Hugo server and view the site in a local web browser:
yarn run server
Here are some things you might try if you encounter an issue working with the site:
- Run
yarn hugo-versionto print the running version of Hugo. Version 0.34 or newer is required. - Did you clone the repository without submodules? See the "cloning the project" section for how to add submodules after the fact.
- If you are seeing stale page content, try using
yarn server --disableFastRenderto ensure all pages are rebuilt as you make changes. - If you're still having trouble viewing the site, open an issue, and we'll be happy to help!
This is the same as any other project. Follow GitHub's instructions if you're unsure. No additional steps are needed.
This project uses Travis CI Deployment support for Heroku to automatically deploy the site once changes are merged to master. For additional details on Heroku configuration and deployment, see our wiki page.